Add Starter Tutorial

.github/workflows/workspace.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   create-workspace:
-    if: github.event.pull_request.merged == true
+    if: github.event.pull_request.merged == true && !contains(github.event.pull_request.labels.*.name, 'Skip CI')
     runs-on: ubuntu-latest
 
     steps:

README.md

@@ -40,7 +40,7 @@ Then start the development server:
 npm run dev
 ```
 
-This will start your site on your local machine. You can now edit the tutorial content in the `src` folder. Tutorials support markdown, markdoc, and HTML. You can view some sample components in the docs folder in the repo. 
+This will start your site on your local machine. You can now edit the tutorial content in the `src` folder. Tutorials support markdown, markdoc, and HTML. Once you are done, add a small synopsis to the README.md file in your tutorial's folder.
 
 ### Create the Tutorial Config
 
@@ -52,8 +52,6 @@ This will create a `tutorial-config.json` file. For example:
 
 ```json
 {
-  "title": "Messages API - SMS (Node.js)",
-  "slug": "messages_api-node-sms", // Your tutorial folder name
   "files": [
     "send-sms.js" // The files needed for the tutorial
   ],
@@ -81,4 +79,4 @@ To update a tutorial:
     * Ensure the version number is updated. 
 * Create a PR
 
-The rest of the steps are the same.
+The rest of the steps are the same.

tutorials/00_Starter-Tutorial/.astro/astro/content.d.ts

@@ -0,0 +1,224 @@
+declare module 'astro:content' {
+	interface Render {
+		'.mdoc': Promise<{
+			Content(props: Record<string, any>): import('astro').MarkdownInstance<{}>['Content'];
+			headings: import('astro').MarkdownHeading[];
+		}>;
+	}
+}
+
+declare module 'astro:content' {
+	interface Render {
+		'.mdx': Promise<{
+			Content: import('astro').MarkdownInstance<{}>['Content'];
+			headings: import('astro').MarkdownHeading[];
+			remarkPluginFrontmatter: Record<string, any>;
+			components: import('astro').MDXInstance<{}>['components'];
+		}>;
+	}
+}
+
+declare module 'astro:content' {
+	interface RenderResult {
+		Content: import('astro/runtime/server/index.js').AstroComponentFactory;
+		headings: import('astro').MarkdownHeading[];
+		remarkPluginFrontmatter: Record<string, any>;
+	}
+	interface Render {
+		'.md': Promise<RenderResult>;
+	}
+
+	export interface RenderedContent {
+		html: string;
+		metadata?: {
+			imagePaths: Array<string>;
+			[key: string]: unknown;
+		};
+	}
+}
+
+declare module 'astro:content' {
+	type Flatten<T> = T extends { [K: string]: infer U } ? U : never;
+
+	export type CollectionKey = keyof AnyEntryMap;
+	export type CollectionEntry<C extends CollectionKey> = Flatten<AnyEntryMap[C]>;
+
+	export type ContentCollectionKey = keyof ContentEntryMap;
+	export type DataCollectionKey = keyof DataEntryMap;
+
+	type AllValuesOf<T> = T extends any ? T[keyof T] : never;
+	type ValidContentEntrySlug<C extends keyof ContentEntryMap> = AllValuesOf<
+		ContentEntryMap[C]
+	>['slug'];
+
+	/** @deprecated Use `getEntry` instead. */
+	export function getEntryBySlug<
+		C extends keyof ContentEntryMap,
+		E extends ValidContentEntrySlug<C> | (string & {}),
+	>(
+		collection: C,
+		// Note that this has to accept a regular string too, for SSR
+		entrySlug: E,
+	): E extends ValidContentEntrySlug<C>
+		? Promise<CollectionEntry<C>>
+		: Promise<CollectionEntry<C> | undefined>;
+
+	/** @deprecated Use `getEntry` instead. */
+	export function getDataEntryById<C extends keyof DataEntryMap, E extends keyof DataEntryMap[C]>(
+		collection: C,
+		entryId: E,
+	): Promise<CollectionEntry<C>>;
+
+	export function getCollection<C extends keyof AnyEntryMap, E extends CollectionEntry<C>>(
+		collection: C,
+		filter?: (entry: CollectionEntry<C>) => entry is E,
+	): Promise<E[]>;
+	export function getCollection<C extends keyof AnyEntryMap>(
+		collection: C,
+		filter?: (entry: CollectionEntry<C>) => unknown,
+	): Promise<CollectionEntry<C>[]>;
+
+	export function getEntry<
+		C extends keyof ContentEntryMap,
+		E extends ValidContentEntrySlug<C> | (string & {}),
+	>(entry: {
+		collection: C;
+		slug: E;
+	}): E extends ValidContentEntrySlug<C>
+		? Promise<CollectionEntry<C>>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof DataEntryMap,
+		E extends keyof DataEntryMap[C] | (string & {}),
+	>(entry: {
+		collection: C;
+		id: E;
+	}): E extends keyof DataEntryMap[C]
+		? Promise<DataEntryMap[C][E]>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof ContentEntryMap,
+		E extends ValidContentEntrySlug<C> | (string & {}),
+	>(
+		collection: C,
+		slug: E,
+	): E extends ValidContentEntrySlug<C>
+		? Promise<CollectionEntry<C>>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof DataEntryMap,
+		E extends keyof DataEntryMap[C] | (string & {}),
+	>(
+		collection: C,
+		id: E,
+	): E extends keyof DataEntryMap[C]
+		? Promise<DataEntryMap[C][E]>
+		: Promise<CollectionEntry<C> | undefined>;
+
+	/** Resolve an array of entry references from the same collection */
+	export function getEntries<C extends keyof ContentEntryMap>(
+		entries: {
+			collection: C;
+			slug: ValidContentEntrySlug<C>;
+		}[],
+	): Promise<CollectionEntry<C>[]>;
+	export function getEntries<C extends keyof DataEntryMap>(
+		entries: {
+			collection: C;
+			id: keyof DataEntryMap[C];
+		}[],
+	): Promise<CollectionEntry<C>[]>;
+
+	export function render<C extends keyof AnyEntryMap>(
+		entry: AnyEntryMap[C][string],
+	): Promise<RenderResult>;
+
+	export function reference<C extends keyof AnyEntryMap>(
+		collection: C,
+	): import('astro/zod').ZodEffects<
+		import('astro/zod').ZodString,
+		C extends keyof ContentEntryMap
+			? {
+					collection: C;
+					slug: ValidContentEntrySlug<C>;
+				}
+			: {
+					collection: C;
+					id: keyof DataEntryMap[C];
+				}
+	>;
+	// Allow generic `string` to avoid excessive type errors in the config
+	// if `dev` is not running to update as you edit.
+	// Invalid collection names will be caught at build time.
+	export function reference<C extends string>(
+		collection: C,
+	): import('astro/zod').ZodEffects<import('astro/zod').ZodString, never>;
+
+	type ReturnTypeOrOriginal<T> = T extends (...args: any[]) => infer R ? R : T;
+	type InferEntrySchema<C extends keyof AnyEntryMap> = import('astro/zod').infer<
+		ReturnTypeOrOriginal<Required<ContentConfig['collections'][C]>['schema']>
+	>;
+
+	type ContentEntryMap = {
+		"docs": {
+"01-welcome.md": {
+	id: "01-welcome.md";
+  slug: "01-welcome";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".md"] };
+"02-install-server-sdk.md": {
+	id: "02-install-server-sdk.md";
+  slug: "02-install-server-sdk";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".md"] };
+"03-initialize-client.md": {
+	id: "03-initialize-client.md";
+  slug: "03-initialize-client";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".md"] };
+"04-send-sms-code.md": {
+	id: "04-send-sms-code.md";
+  slug: "04-send-sms-code";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".md"] };
+"05-run-code.md": {
+	id: "05-run-code.md";
+  slug: "05-run-code";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".md"] };
+"06-whats-next.md": {
+	id: "06-whats-next.md";
+  slug: "06-whats-next";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".md"] };
+"index.mdx": {
+	id: "index.mdx";
+  slug: "index";
+  body: string;
+  collection: "docs";
+  data: InferEntrySchema<"docs">
+} & { render(): Render[".mdx"] };
+};
+
+	};
+
+	type DataEntryMap = {
+
+	};
+
+	type AnyEntryMap = ContentEntryMap & DataEntryMap;
+
+	export type ContentConfig = typeof import("../../src/content/config.js");
+}

tutorials/00_Starter-Tutorial/.astro/settings.json

@@ -0,0 +1,5 @@
+{
+	"_variables": {
+		"lastUpdateCheck": 1732190170983
+	}
+}

tutorials/00_Starter-Tutorial/.astro/types.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="astro/client" />
+/// <reference path="astro/content.d.ts" />

tutorials/00_Starter-Tutorial/README.md

@@ -0,0 +1,3 @@
+# Starter Onboarding Tutorial
+
+This is a starter tutorial.

tutorials/00_Starter-Tutorial/astro.config.mjs

@@ -0,0 +1,20 @@
+import { defineConfig } from 'astro/config';
+
+import markdoc from '@astrojs/markdoc';
+import starlight from '@astrojs/starlight';
+import relativeLinks from 'astro-relative-links';
+import vonageIntegration from './vonage-toolbar/integration.ts';
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [
+    relativeLinks(),
+    vonageIntegration,
+    starlight({
+      title: 'Vonage Onboarding',
+      tableOfContents: false,
+      pagefind: false,
+    }),
+    markdoc({ allowHTML: true })
+  ],
+});

tutorials/00_Starter-Tutorial/download-toolbar.js

@@ -0,0 +1,36 @@
+import fs from 'fs/promises';
+
+async function downloadFile(url, filename) {
+  console.log('downloading: ', filename);
+  try {
+    const response = await fetch(url);
+    const buffer = await response.arrayBuffer();
+
+    await fs.mkdir('./vonage-toolbar', { recursive: true }); // Create the downloads directory if it doesn't exist
+    await fs.writeFile(
+      `./vonage-toolbar/${filename}`,
+      Buffer.from(buffer),
+      (err) => {
+        if (err) {
+          console.error('Error writing file:', err);
+        } else {
+          console.log('File downloaded and written successfully!');
+        }
+      }
+    );
+  } catch (error) {
+    console.error('Error downloading file:', error);
+  }
+}
+
+console.log('download toolbar application files');
+
+downloadFile(
+  'https://raw.githubusercontent.com/vonage-community/tutorial-interactive_tutorials/refs/heads/main/toolbar-app/vonage-toolbar/integration.ts',
+  'integration.ts'
+);
+
+downloadFile(
+  'https://raw.githubusercontent.com/vonage-community/tutorial-interactive_tutorials/refs/heads/main/toolbar-app/vonage-toolbar/app.ts',
+  'app.ts'
+);

tutorials/00_Starter-Tutorial/markdoc.config.mjs

@@ -0,0 +1,6 @@
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import starlightMarkdoc from '@astrojs/starlight-markdoc';
+
+export default defineMarkdocConfig({
+  extends: [starlightMarkdoc()],
+});

tutorials/00_Starter-Tutorial/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "vonage-interactive-tutorial",
+  "type": "module",
+  "version": "1.0.0",
+  "scripts": {
+    "astro": "astro",
+    "dev": "astro dev",
+    "build": "astro build",
+    "postinstall": "node download-toolbar.js"
+  },
+  "dependencies": {
+    "@astrojs/markdoc": "^0.11.5",
+    "@astrojs/starlight": "^0.28.6",
+    "@astrojs/starlight-markdoc": "^0.1.0",
+    "astro": "^4.15.3",
+    "astro-relative-links": "^0.4.0",
+    "sharp": "^0.32.5",
+    "adm-zip": "^0.5.16"
+  }
+}

tutorials/00_Starter-Tutorial/src/content/config.ts

@@ -0,0 +1,6 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ schema: docsSchema() }),
+};

tutorials/00_Starter-Tutorial/src/content/docs/01-welcome.md

@@ -0,0 +1,8 @@
+---
+title: Introduction
+description: An introduction to the onboarding tutorial
+---
+
+# Starter Tutorial
+
+This is a paragraph about what the tutorial contains.

tutorials/00_Starter-Tutorial/src/content/docs/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Starter Tutorial
+description: Get started building a tutorial.
+template: splash
+hero:
+  tagline: Starting a tutorial!
+---

tutorials/00_Starter-Tutorial/src/env.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="astro/client" />

tutorials/00_Starter-Tutorial/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "astro/tsconfigs/strict"
+}