@swirls/sdk 0.0.1

package/README.md

@@ -0,0 +1,35 @@
+# @swirls/sdk
+
+TypeScript SDK for building applications powered by Swirls.
+
+## Overview
+
+The Swirls SDK provides utilities for integrating Swirls into your applications. It is designed to be type-safe, headless, and framework-agnostic.
+
+### Configuration
+
+The [`@swirls/sdk/config`](src/config/README.md) subpackage provides configuration "glue" that connects your application to a Swirls project and powers code generation.
+
+```typescript
+import { defineConfig } from '@swirls/sdk/config'
+```
+
+### Forms
+
+The [`@swirls/sdk/form`](src/form/README.md) subpackage provides a form library for building, validating, and submitting forms.
+
+```typescript
+import { useSwirlsFormAdapter, SwirlsForm } from '@swirls/sdk/form'
+```
+
+## Installation
+
+```sh
+bun add @swirls/sdk react zod
+```
+
+## Learn More
+
+- [Swirls Documentation](https://docs.swirls.dev): Full platform documentation
+- [Config Documentation](src/config/README.md): Configuration reference
+- [Form Documentation](src/form/README.md): Complete guide to forms

package/dist/config/config.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+declare const configFileName = "swirls.config.ts";
+declare const configSchema: z.ZodObject<{
+    projectId: z.ZodUUID;
+    genPath: z.ZodString;
+}, z.core.$strip>;
+type Config = z.infer<typeof configSchema>;
+type ConfigOptions = {
+    /**
+     * Identifier of the Swirls project to use.
+     */
+    projectId: string;
+    /**
+     * Path defining the location of the generated code.
+     * @default 'src/swirls.gen.ts'
+     */
+    genPath?: string;
+};
+/**
+ * Defines a Swirls configuration with optional defaults.
+ */
+declare function defineConfig(config: ConfigOptions): Config;
+/**
+ * Generates a Swirls configuration skeleton with default and empty values.
+ */
+declare function generateConfig(projectId?: string): string;
+
+export { configFileName, configSchema, defineConfig, generateConfig };

package/dist/config/config.js

@@ -0,0 +1,39 @@
+// src/config/config.ts
+import path from "path";
+import { z } from "zod";
+var configFileName = "swirls.config.ts";
+var configImportPath = "@swirls/sdk/config";
+var generatedFileName = "swirls.gen.ts";
+var configSchema = z.object({
+  projectId: z.uuid(),
+  genPath: z.string().min(1)
+});
+function defineConfig(config) {
+  const root = process.cwd();
+  const source = path.join(root, "src");
+  const output = path.join(source, generatedFileName);
+  return {
+    projectId: config.projectId,
+    genPath: config.genPath ?? output
+  };
+}
+function generateConfig(projectId) {
+  const lines = [
+    `import { defineConfig } from '${configImportPath}'`,
+    "",
+    "export default defineConfig({",
+    "  // swirls project identifier",
+    `  projectId: '${projectId || ""}',`,
+    "  // path to generated code",
+    `  genPath: 'src/${generatedFileName}',`,
+    "})",
+    ""
+  ];
+  return lines.join("\n");
+}
+export {
+  configFileName,
+  configSchema,
+  defineConfig,
+  generateConfig
+};

package/dist/form/form.d.ts

@@ -0,0 +1,99 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { z } from 'zod';
+
+type Schema = z.ZodTypeAny;
+type Value<S extends Schema> = z.input<S>;
+
+interface FormRegistry {
+}
+type RegistryFormName = Extract<keyof FormRegistry, string>;
+type FormName = [RegistryFormName] extends [never] ? string : RegistryFormName;
+type FormDefinition<K extends string = string, S extends Schema = Schema> = {
+    id: string;
+    name: K;
+    schema: S;
+};
+type FormEntry<K extends FormName> = K extends keyof FormRegistry ? FormRegistry[K] & FormDefinition : FormDefinition;
+declare function registerForm<K extends FormName>(name: K, form: FormEntry<K>): void;
+/**
+ * Hook that returns a form adapter for integrating Swirls forms with your form library.
+ *
+ * The adapter is a bridge object that provides validation, submission, and schema information
+ * for a specific Swirls form. It allows you to wire up Swirls forms with any form library
+ * (React Hook Form, TanStack Form, Formik, or plain React state).
+ *
+ * **Returns:** A form adapter object with:
+ * - `submit(value)` - Submits form data to the Swirls API and triggers the workflow
+ * - `schema` - The Zod schema for the form (useful for form library resolvers)
+ * - `defaultValues` - Typed default values for the form
+ *
+ * **Access:** The adapter is returned directly from the hook. Use it to wire up your form library.
+ *
+ * @example
+ * ```tsx
+ * // TanStack Form
+ * import { useForm } from '@tanstack/react-form'
+ *
+ * // Swirls Form Adapter
+ * const adapter = useSwirlsFormAdapter('contact-form', { email: '' })
+ *
+ * const form = useForm({
+ *   defaultValues: adapter.defaultValues,
+ *   validators: {
+ *     onChange: adapter.schema.parse,
+ *   },
+ *   onSubmit: ({ value }) => adapter.submit(value),
+ * })
+ * ```
+ *
+ * @param name - The name of the form (autocompleted from registered forms)
+ * @param defaultValues - Typed default values matching the form schema
+ * @returns Form adapter object for wiring up with your form library
+ */
+declare function useSwirlsFormAdapter<K extends FormName>(name: K, defaultValues: Value<FormEntry<K>['schema']>): {
+    submit: (value: Value<FormEntry<K>["schema"]>) => Promise<{
+        executionIds: string[];
+        message: string;
+        pizza: boolean;
+    }>;
+    schema: Schema;
+    defaultValues: Value<FormEntry<K>["schema"]>;
+};
+/**
+ * Render props component that provides a form adapter for integrating Swirls forms.
+ *
+ * The adapter is a bridge object that provides validation, submission, and schema information
+ * for a specific Swirls form. This component wraps `useSwirlsFormAdapter` and provides the
+ * adapter via a render prop, making it convenient for simpler form implementations.
+ *
+ * **Returns:** Renders the children function with the adapter as an argument.
+ *
+ * **Access:** The adapter is passed to the `children` render function. Use it within your
+ * form JSX to access validation, submission, schema, and defaultValues.
+ *
+ * @example
+ * ```tsx
+ * <SwirlsForm schemaName="contact-form" defaultValues={{ name: '', email: '' }}>
+ *   {(adapter) => (
+ *     <form onSubmit={async (e) => {
+ *       e.preventDefault()
+ *       await adapter.submit(formData)
+ *     }}>
+ *       {/* ... *\/}
+ *     </form>
+ *   )}
+ * </SwirlsForm>
+ * ```
+ *
+ * @param name - The name of the form (autocompleted from registered forms)
+ * @param defaultValues - Typed default values matching the form schema
+ * @param children - Render function that receives the adapter object
+ */
+declare function SwirlsForm<K extends FormName>({ name, defaultValues, children, }: {
+    name: K;
+    defaultValues: Value<FormEntry<K>['schema']>;
+    children: (adapter: ReturnType<typeof useSwirlsFormAdapter<K>>) => React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+export { type FormRegistry, SwirlsForm, registerForm, useSwirlsFormAdapter };

package/dist/form/form.js

@@ -0,0 +1,75 @@
+// src/form/submit.ts
+import { z } from "zod";
+var API_URL = "https://api.swirls.ai";
+async function submitForm(form, value) {
+  const submission = parseSubmission(form.schema, value);
+  const response = await fetch(`${API_URL}/forms/${form.id}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(submission)
+  });
+  if (!response.ok) {
+    const { message } = await response.json();
+    throw new Error(message);
+  }
+  return parseResponse(response);
+}
+function parseSubmission(schema, value) {
+  const parse = schema.safeParse(value);
+  if (!parse.success) {
+    const message = z.prettifyError(parse.error);
+    throw new Error(`Invalid submission: ${message}`, {
+      cause: parse.error
+    });
+  }
+  return parse.data;
+}
+var responseSchema = z.object({
+  executionIds: z.array(z.string()),
+  message: z.string(),
+  pizza: z.boolean()
+});
+async function parseResponse(response) {
+  const result = await response.json();
+  return responseSchema.parse(result);
+}
+
+// src/form/form.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+var formRegistry = {};
+function registerForm(name, form) {
+  formRegistry[name] = form;
+}
+function getForm(name) {
+  return formRegistry[name];
+}
+function useSwirlsFormAdapter(name, defaultValues) {
+  const form = getForm(name);
+  if (!form) {
+    throw new Error(
+      `Form "${name}" is not registered. Did you call registerForms()?`
+    );
+  }
+  return {
+    submit: (value) => {
+      return submitForm(form, value);
+    },
+    schema: form.schema,
+    defaultValues
+  };
+}
+function SwirlsForm({
+  name,
+  defaultValues,
+  children
+}) {
+  const adapter = useSwirlsFormAdapter(name, defaultValues);
+  return /* @__PURE__ */ jsx(Fragment, { children: children(adapter) });
+}
+export {
+  SwirlsForm,
+  registerForm,
+  useSwirlsFormAdapter
+};

package/dist/form/generate.d.ts

@@ -0,0 +1,10 @@
+import { JsonSchema } from '@swirls/core/schemas';
+
+type Form = {
+    id: string;
+    name: string;
+    schema: JsonSchema;
+};
+declare function generateFormsCode(forms: Form[], header: string[]): string;
+
+export { generateFormsCode };

package/dist/form/generate.js

@@ -0,0 +1,87 @@
+// src/form/generate.ts
+import { jsonSchemaToZod } from "json-schema-to-zod";
+import { camelCase, pascalCase } from "text-case";
+function generateFormsCode(forms, header) {
+  const imports = [
+    `import { registerForm } from '@swirls/sdk/form'`,
+    `import { z } from 'zod'`,
+    ""
+  ];
+  const schemas = forms.flatMap(
+    ({ name, schema }) => generateStandardSchema(name, schema)
+  );
+  return [
+    ...header,
+    ...imports,
+    ...schemas,
+    ...generateRegistry(forms),
+    ...generateRegisterFunction(forms),
+    ...generateModuleAugmentation(forms)
+  ].join("\n");
+}
+function generateStandardSchema(name, schema) {
+  const output = jsonSchemaToZod(schema, {
+    module: "esm",
+    name: schemaName(name).camel,
+    noImport: true,
+    type: true
+  });
+  const [object, type] = output.split("\n");
+  if (!object || !type) {
+    throw new Error("Failed to generate standard schema");
+  }
+  return [`// Form schema: ${name}`, object, "", type, ""];
+}
+function generateRegistry(forms) {
+  return [
+    "// Form registry",
+    "export const registry = {",
+    ...forms.flatMap(({ name, id }) => [
+      `  '${name}': {`,
+      `    id: '${id}',`,
+      `    name: '${name}',`,
+      `    schema: ${schemaName(name).camel},`,
+      "  },"
+    ]),
+    "} as const",
+    ""
+  ];
+}
+function generateRegisterFunction(forms) {
+  return [
+    "// Form registration",
+    "export function registerForms() {",
+    ...forms.map(({ name }) => {
+      return `  registerForm('${name}', registry['${name}'])`;
+    }),
+    "}",
+    ""
+  ];
+}
+function generateModuleAugmentation(forms) {
+  const module = "@swirls/sdk/form";
+  return [
+    `// Module augmentation for ${module}`,
+    `declare module '${module}' {`,
+    "  interface FormRegistry {",
+    ...forms.flatMap(({ name, id }) => [
+      `    '${name}': {`,
+      `      id: '${id}'`,
+      `      name: '${name}'`,
+      `      schema: typeof ${schemaName(name).camel}`,
+      "    }"
+    ]),
+    "  }",
+    "}",
+    ""
+  ];
+}
+function schemaName(name) {
+  return {
+    camel: `${camelCase(name)}Schema`,
+    pascal: `${pascalCase(name)}Schema`
+  };
+}
+export {
+  generateFormsCode
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@swirls/sdk",
+  "version": "0.0.1",
+  "description": "Swirls SDK",
+  "author": {
+    "name": "Swirls",
+    "url": "https://swirls.ai"
+  },
+  "type": "module",
+  "exports": {
+    "./form": "./dist/form/form.js",
+    "./form/generate": "./dist/form/generate.js",
+    "./config": "./dist/config/config.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "pkg:publish": "bun publish",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@swirls/core": "0.0.1",
+    "json-schema-to-zod": "2.7.0",
+    "text-case": "1.2.9",
+    "zod": "4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "@types/react": "19.2.6",
+    "react": "19.2.1",
+    "tsup": "8.5.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}