skedyul 0.3.20 → 1.0.2

package/README.md

@@ -2,6 +2,10 @@
 
 The official Node.js SDK for building Skedyul integration apps. This package provides everything you need to create MCP (Model Context Protocol) servers, handle webhooks, manage lifecycle events, and interact with the Skedyul platform.
 
+## Version 1.0.0
+
+This release introduces a modular, file-based configuration system with improved type safety and developer experience.
+
 ## Features
 
 - **MCP Server**: Build tools that AI agents can invoke via the Model Context Protocol
@@ -9,6 +13,7 @@ The official Node.js SDK for building Skedyul integration apps. This package pro
 - **Lifecycle Hooks**: Handle app installation, provisioning, and cleanup
 - **Core API Client**: Interact with Skedyul resources (workplaces, channels, instances)
 - **CLI**: Develop and test locally with hot-reload and tunneling
+- **Modular Config**: File-based configuration with auto-discovery patterns
 
 ## Installation
 
@@ -25,17 +30,76 @@ pnpm add skedyul
 ```ts
 // skedyul.config.ts
 import { defineConfig } from 'skedyul'
+import pkg from './package.json'
 
 export default defineConfig({
-  name: 'my-integration',
-  version: '1.0.0',
+  name: 'My Integration',
+  version: pkg.version,
+  description: 'Description of what this app does',
   computeLayer: 'serverless',
-  tools: import('./src/tools/registry'),
-  webhooks: import('./src/webhooks/registry'),
+
+  tools: import('./src/registries'),
+  webhooks: import('./src/registries'),
+  provision: import('./provision'),
 })
 ```
 
-### 2. Define a tool
+### 2. Define your provision config
+
+```ts
+// provision.ts
+import type { ProvisionConfig } from 'skedyul'
+
+import env from './env'
+import { models, relationships } from './crm'
+import * as channels from './channels'
+import * as pages from './pages'
+import navigation from './pages/navigation'
+
+const config: ProvisionConfig = {
+  env,
+  navigation,
+  models: Object.values(models),
+  channels: Object.values(channels),
+  pages: Object.values(pages),
+  relationships,
+}
+
+export default config
+```
+
+### 3. Define a model
+
+```ts
+// crm/models/contact.ts
+import { defineModel } from 'skedyul'
+
+export default defineModel({
+  handle: 'contact',
+  label: 'Contact',
+  labelPlural: 'Contacts',
+  scope: 'shared',
+
+  fields: [
+    {
+      handle: 'name',
+      label: 'Name',
+      type: 'string',
+      required: true,
+      owner: 'workplace',
+    },
+    {
+      handle: 'email',
+      label: 'Email',
+      type: 'string',
+      required: false,
+      owner: 'workplace',
+    },
+  ],
+})
+```
+
+### 4. Define a tool
 
 ```ts
 // src/tools/hello.ts
@@ -65,7 +129,7 @@ export const helloTool: ToolDefinition<Input, Output> = {
 }
 ```
 
-### 3. Start the server
+### 5. Start the server
 
 ```ts
 // src/server.ts
@@ -95,6 +159,33 @@ await mcpServer.listen(3000)
 | [Configuration](./docs/configuration.md) | skedyul.config.ts reference |
 | [Errors](./docs/errors.md) | Error types and handling patterns |
 
+## Project Structure
+
+The recommended project structure uses modular, file-based configuration:
+
+```
+my-app/
+├── skedyul.config.ts          # App metadata + imports
+├── provision.ts               # Aggregates all modular configs
+├── env.ts                     # Environment variables
+├── crm/
+│   ├── index.ts               # Re-exports models + relationships
+│   ├── relationships.ts       # Model relationships
+│   └── models/
+│       ├── index.ts
+│       └── contact.ts
+├── channels/
+│   ├── index.ts
+│   └── phone.ts
+├── pages/
+│   ├── index.ts
+│   ├── navigation.ts          # Root navigation
+│   └── settings/
+│       └── page.ts
+└── src/
+    └── registries.ts          # Tools and webhooks
+```
+
 ## Server Modes
 
 ### Dedicated (Docker/ECS)

package/dist/.build-stamp

@@ -1 +1 @@
-1771902906904
+1771999780767

package/dist/cli/commands/invoke.js

@@ -42,6 +42,101 @@ const logger_1 = require("../../server/logger");
 const auth_1 = require("../utils/auth");
 const link_1 = require("../utils/link");
 const config_1 = require("../utils/config");
+const client_1 = require("../../core/client");
+/**
+ * Simple MIME type lookup based on file extension.
+ */
+function getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const mimeTypes = {
+        '.pdf': 'application/pdf',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.png': 'image/png',
+        '.gif': 'image/gif',
+        '.webp': 'image/webp',
+        '.svg': 'image/svg+xml',
+        '.txt': 'text/plain',
+        '.html': 'text/html',
+        '.htm': 'text/html',
+        '.css': 'text/css',
+        '.js': 'application/javascript',
+        '.json': 'application/json',
+        '.xml': 'application/xml',
+        '.csv': 'text/csv',
+        '.doc': 'application/msword',
+        '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        '.xls': 'application/vnd.ms-excel',
+        '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        '.zip': 'application/zip',
+        '.mp3': 'audio/mpeg',
+        '.mp4': 'video/mp4',
+        '.wav': 'audio/wav',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
+}
+/**
+ * Upload a local file and return its file ID.
+ */
+async function uploadLocalFile(filePath) {
+    const absolutePath = path.resolve(filePath);
+    if (!fs.existsSync(absolutePath)) {
+        throw new Error(`File not found: ${absolutePath}`);
+    }
+    const content = fs.readFileSync(absolutePath);
+    const fileName = path.basename(absolutePath);
+    const mimeType = getMimeType(absolutePath);
+    console.error(`Uploading file: ${fileName} (${mimeType}, ${content.length} bytes)...`);
+    const result = await client_1.file.upload({
+        content,
+        name: fileName,
+        mimeType,
+    });
+    console.error(`Uploaded: ${fileName} -> ${result.id}`);
+    return result.id;
+}
+/**
+ * Process upload templates in args object.
+ * Recursively scans all string values and replaces {{upload:/path/to/file}} patterns
+ * with the uploaded file ID.
+ */
+async function processUploadTemplates(args) {
+    const result = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === 'string') {
+            const match = value.match(/^\{\{upload:(.+)\}\}$/);
+            if (match) {
+                const filePath = match[1];
+                const fileId = await uploadLocalFile(filePath);
+                result[key] = fileId;
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        else if (Array.isArray(value)) {
+            result[key] = await Promise.all(value.map(async (item) => {
+                if (typeof item === 'string') {
+                    const match = item.match(/^\{\{upload:(.+)\}\}$/);
+                    if (match) {
+                        return await uploadLocalFile(match[1]);
+                    }
+                }
+                else if (item && typeof item === 'object') {
+                    return await processUploadTemplates(item);
+                }
+                return item;
+            }));
+        }
+        else if (value && typeof value === 'object') {
+            result[key] = await processUploadTemplates(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
 /**
  * Find available linked workplaces from .skedyul/links/
  */
@@ -73,6 +168,7 @@ Arguments:
 Options:
   --registry, -r      Path to the registry file (default: auto-detected)
   --args, -a          JSON string of arguments to pass to the tool
+                      Supports {{upload:/path/to/file}} syntax for file uploads
   --env, -e           Set environment variable (can be used multiple times)
                       Format: --env KEY=VALUE
   --env-file          Load environment variables from a file (e.g., .env.local)
@@ -83,6 +179,10 @@ Workplace Options:
   --workplace, -w     Workplace subdomain (auto-detected if only one is linked)
                       Loads env vars from .skedyul/env/{workplace}.env
 
+File Upload Syntax:
+  Use {{upload:/path/to/file}} in any string field within --args to automatically
+  upload a local file and replace the template with the uploaded file ID.
+
 Examples:
   # Basic invocation (auto-detects workspace if only one is linked)
   skedyul dev invoke appointment_types_list
@@ -93,6 +193,14 @@ Examples:
   # With arguments
   skedyul dev invoke create_booking --args '{"date": "2024-01-15"}'
 
+  # With file upload (uploads file and injects file_id)
+  skedyul dev invoke parse_lab_report \\
+    --args '{"file_id": "{{upload:/path/to/report.pdf}}"}'
+
+  # Multiple file uploads in one command
+  skedyul dev invoke process_documents \\
+    --args '{"doc": "{{upload:./doc.pdf}}", "image": "{{upload:./photo.jpg}}"}'
+
   # With inline environment variables
   skedyul dev invoke api_call \\
     --args '{"endpoint": "/users"}' \\
@@ -209,12 +317,27 @@ async function invokeCommand(args) {
             const tokenResponse = await (0, auth_1.callCliApi)({ serverUrl: linkConfig.serverUrl, token: credentials.token }, '/token', { appInstallationId: linkConfig.appInstallationId });
             workplaceToken = tokenResponse.token;
             env.SKEDYUL_API_TOKEN = workplaceToken;
+            // Configure the skedyul client for file uploads
+            (0, client_1.configure)({
+                baseUrl: linkConfig.serverUrl,
+                apiToken: workplaceToken,
+            });
         }
         catch (error) {
             console.error(`Failed to get API token: ${error instanceof Error ? error.message : String(error)}`);
             process.exit(1);
         }
     }
+    // Process upload templates in args (e.g., {{upload:/path/to/file}})
+    if (isLinked) {
+        try {
+            toolArgs = await processUploadTemplates(toolArgs);
+        }
+        catch (error) {
+            console.error(`Error processing file uploads: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
     // Check for estimate mode
     const estimateMode = Boolean(flags.estimate);
     // Load registry

package/dist/cli/utils/config.js

@@ -90,9 +90,14 @@ function parseConfigFromSource(configPath) {
         }
         // Fallback: try to extract handle from config file (top-level only)
         if (!handle) {
-            const handleMatch = content.match(/^\s*handle\s*:\s*['"`]([^'"`]+)['"`]/m);
+            const handleMatch = content.match(/^\s{0,2}handle\s*:\s*['"`]([^'"`]+)['"`]/m);
             handle = handleMatch?.[1] ?? null;
         }
+        // If handle was found in config, prefer it over package.json derived handle
+        const configHandleMatch = content.match(/^\s{0,2}handle\s*:\s*['"`]([^'"`]+)['"`]/m);
+        if (configHandleMatch?.[1]) {
+            handle = configHandleMatch[1];
+        }
         if (!handle && !nameMatch) {
             return null;
         }

package/dist/config/types/model.d.ts

@@ -10,7 +10,8 @@ import type { ResourceDependency } from './resource';
 /**
  * Field data types (lowercase).
  * - 'string': Short text (single line)
- * - 'text': Long text (multi-line)
+ * - 'long_string': Long text (multi-line, stored as text in DB)
+ * - 'text': Alias for long_string
  * - 'number': Numeric value
  * - 'boolean': True/false
  * - 'date': Date only (no time)
@@ -21,7 +22,7 @@ import type { ResourceDependency } from './resource';
  * - 'relation': Reference to another model
  * - 'object': JSON object
  */
-export type FieldType = 'string' | 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'time' | 'file' | 'image' | 'relation' | 'object';
+export type FieldType = 'string' | 'long_string' | 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'time' | 'file' | 'image' | 'relation' | 'object';
 /**
  * Relationship cardinality between models.
  */

package/dist/config/types/page.d.ts

@@ -4,7 +4,7 @@
  * Pages define the UI screens for an app, including their
  * layout, data context, and navigation.
  */
-import type { BaseDefinition } from './base';
+import type { BaseDefinition, StructuredFilter } from './base';
 import type { ContextDefinition } from './context';
 import type { ActionDefinition, BlockDefinition } from './form';
 import type { NavigationConfig } from './navigation';
@@ -14,6 +14,16 @@ import type { NavigationConfig } from './navigation';
  * - 'list': Shows multiple records (e.g., /phone-numbers)
  */
 export type PageType = 'instance' | 'list';
+/**
+ * Page filter for list pages.
+ * Defines which model and optional filter criteria to use.
+ */
+export interface PageFilter {
+    /** Model handle to filter */
+    model: string;
+    /** Optional filter criteria */
+    where?: StructuredFilter;
+}
 /**
  * Page definition.
  */
@@ -37,4 +47,6 @@ export interface PageDefinition extends BaseDefinition {
     actions?: ActionDefinition[];
     /** Context data to load for Liquid templates */
     context?: ContextDefinition;
+    /** Filter for list pages - defines which model instances to show */
+    filter?: PageFilter;
 }

package/dist/core/client.d.ts

@@ -382,6 +382,21 @@ export interface FileUrlResponse {
     /** ISO timestamp when the URL expires */
     expiresAt: string;
 }
+/**
+ * Response from file.get
+ */
+export interface FileInfo {
+    /** File ID (fl_xxx format) */
+    id: string;
+    /** Original filename */
+    name: string;
+    /** MIME type of the file */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** ISO timestamp when the file was created */
+    createdAt: string;
+}
 /**
  * Parameters for file.upload
  */
@@ -405,6 +420,22 @@ export interface FileUploadResult {
     url: string | null;
 }
 export declare const file: {
+    /**
+     * Get file metadata by ID.
+     *
+     * Returns file information including name, mimeType, and size.
+     * Files are validated to ensure they belong to the requesting app installation.
+     *
+     * @example
+     * ```ts
+     * // Get file info
+     * const fileInfo = await file.get('fl_abc123')
+     * console.log(fileInfo.name) // 'document.pdf'
+     * console.log(fileInfo.mimeType) // 'application/pdf'
+     * console.log(fileInfo.size) // 12345
+     * ```
+     */
+    get(fileId: string): Promise<FileInfo>;
     /**
      * Get a temporary download URL for an app-scoped file.
      *

package/dist/core/client.js

@@ -5,6 +5,7 @@ exports.runWithConfig = runWithConfig;
 exports.configure = configure;
 exports.getConfig = getConfig;
 const async_hooks_1 = require("async_hooks");
+const v4_1 = require("zod/v4");
 /**
  * AsyncLocalStorage for request-scoped configuration.
  * This allows each request to have its own config without affecting other concurrent requests.
@@ -406,6 +407,27 @@ exports.token = {
     },
 };
 exports.file = {
+    /**
+     * Get file metadata by ID.
+     *
+     * Returns file information including name, mimeType, and size.
+     * Files are validated to ensure they belong to the requesting app installation.
+     *
+     * @example
+     * ```ts
+     * // Get file info
+     * const fileInfo = await file.get('fl_abc123')
+     * console.log(fileInfo.name) // 'document.pdf'
+     * console.log(fileInfo.mimeType) // 'application/pdf'
+     * console.log(fileInfo.size) // 12345
+     * ```
+     */
+    async get(fileId) {
+        const { data } = await callCore('file.get', {
+            fileId,
+        });
+        return data;
+    },
     /**
      * Get a temporary download URL for an app-scoped file.
      *
@@ -642,60 +664,11 @@ exports.contactAssociationLink = {
     },
 };
 /**
- * Convert a Zod schema to JSON Schema format for transport.
- * This is a simplified conversion that handles common Zod types.
+ * Convert a Zod schema to JSON Schema format for transport using Zod's built-in conversion.
+ * Uses z.toJSONSchema() from Zod 4 for accurate schema conversion.
  */
 function zodSchemaToJsonSchema(schema) {
-    // Use Zod's built-in JSON Schema conversion if available
-    // For now, we'll pass the schema description and let the server handle it
-    const jsonSchema = schema._def;
-    // Basic type mapping
-    if (jsonSchema?.typeName === 'ZodString') {
-        return { type: 'string' };
-    }
-    if (jsonSchema?.typeName === 'ZodNumber') {
-        return { type: 'number' };
-    }
-    if (jsonSchema?.typeName === 'ZodBoolean') {
-        return { type: 'boolean' };
-    }
-    if (jsonSchema?.typeName === 'ZodArray') {
-        const arrayDef = jsonSchema;
-        return {
-            type: 'array',
-            items: arrayDef.type ? zodSchemaToJsonSchema(arrayDef.type) : {},
-        };
-    }
-    if (jsonSchema?.typeName === 'ZodObject') {
-        const objectDef = jsonSchema;
-        const shape = objectDef.shape?.() ?? {};
-        const properties = {};
-        const required = [];
-        for (const [key, value] of Object.entries(shape)) {
-            properties[key] = zodSchemaToJsonSchema(value);
-            // Check if field is required (not optional/nullable)
-            const valueDef = value._def;
-            if (valueDef?.typeName !== 'ZodOptional' && valueDef?.typeName !== 'ZodNullable') {
-                required.push(key);
-            }
-        }
-        return {
-            type: 'object',
-            properties,
-            required: required.length > 0 ? required : undefined,
-        };
-    }
-    if (jsonSchema?.typeName === 'ZodNullable' || jsonSchema?.typeName === 'ZodOptional') {
-        const innerDef = jsonSchema;
-        const inner = innerDef.innerType ? zodSchemaToJsonSchema(innerDef.innerType) : {};
-        return { ...inner, nullable: true };
-    }
-    if (jsonSchema?.typeName === 'ZodEnum') {
-        const enumDef = jsonSchema;
-        return { type: 'string', enum: enumDef.values };
-    }
-    // Fallback: return empty object schema
-    return { type: 'object' };
+    return v4_1.z.toJSONSchema(schema);
 }
 exports.ai = {
     /**

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { InstallError, MissingRequiredFieldError, AuthenticationError, InvalidCo
 export type { InstallErrorCode } from './errors';
 export { z };
 export { workplace, communicationChannel, instance, token, file, webhook, resource, contactAssociationLink, ai, configure, getConfig, runWithConfig, } from './core/client';
-export type { InstanceContext, InstanceData, InstanceMeta, InstancePagination, InstanceListResult, InstanceListArgs, FileUrlResponse, FileUploadParams, FileUploadResult, WebhookCreateResult, WebhookListItem, WebhookDeleteByNameOptions, WebhookListOptions, ResourceLinkParams, ResourceLinkResult, ContactAssociationLinkCreateParams, ContactAssociationLinkCreateResult, AITextContent, AIFileContent, AIImageContent, AIMessageContent, AIMessage, GenerateObjectOptions, GenerateObjectResult, } from './core/client';
+export type { InstanceContext, InstanceData, InstanceMeta, InstancePagination, InstanceListResult, InstanceListArgs, FileInfo, FileUrlResponse, FileUploadParams, FileUploadResult, WebhookCreateResult, WebhookListItem, WebhookDeleteByNameOptions, WebhookListOptions, ResourceLinkParams, ResourceLinkResult, ContactAssociationLinkCreateParams, ContactAssociationLinkCreateResult, AITextContent, AIFileContent, AIImageContent, AIMessageContent, AIMessage, GenerateObjectOptions, GenerateObjectResult, } from './core/client';
 export { createContextLogger } from './server/logger';
 export type { ContextLogger } from './server/logger';
 declare const _default: {

package/dist/schemas.d.ts

@@ -1833,7 +1833,7 @@ export declare const ListBlockDefinitionSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** Model mapper block definition - for mapping SHARED models to workspace models */
 export declare const ModelMapperBlockDefinitionSchema: z.ZodObject<{
-    type: z.ZodLiteral<"model-mapper">;
+    type: z.ZodLiteral<"model_mapper">;
     model: z.ZodString;
 }, z.core.$strip>;
 /** Union of all block types */
@@ -2210,7 +2210,7 @@ export declare const PageBlockDefinitionSchema: z.ZodUnion<readonly [z.ZodObject
     icon: z.ZodOptional<z.ZodString>;
     emptyMessage: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"model-mapper">;
+    type: z.ZodLiteral<"model_mapper">;
     model: z.ZodString;
 }, z.core.$strip>]>;
 /** Mode for context data fetching */
@@ -2714,7 +2714,7 @@ export declare const PageDefinitionSchema: z.ZodObject<{
         icon: z.ZodOptional<z.ZodString>;
         emptyMessage: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
-        type: z.ZodLiteral<"model-mapper">;
+        type: z.ZodLiteral<"model_mapper">;
         model: z.ZodString;
     }, z.core.$strip>]>>;
     actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -3505,7 +3505,7 @@ export declare const ProvisionConfigSchema: z.ZodObject<{
             icon: z.ZodOptional<z.ZodString>;
             emptyMessage: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
-            type: z.ZodLiteral<"model-mapper">;
+            type: z.ZodLiteral<"model_mapper">;
             model: z.ZodString;
         }, z.core.$strip>]>>;
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4143,7 +4143,7 @@ export declare const SkedyulConfigSchema: z.ZodObject<{
                 icon: z.ZodOptional<z.ZodString>;
                 emptyMessage: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>, z.ZodObject<{
-                type: z.ZodLiteral<"model-mapper">;
+                type: z.ZodLiteral<"model_mapper">;
                 model: z.ZodString;
             }, z.core.$strip>]>>;
             actions: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/schemas.js

@@ -545,7 +545,7 @@ exports.ListBlockDefinitionSchema = v4_1.z.object({
 });
 /** Model mapper block definition - for mapping SHARED models to workspace models */
 exports.ModelMapperBlockDefinitionSchema = v4_1.z.object({
-    type: v4_1.z.literal('model-mapper'),
+    type: v4_1.z.literal('model_mapper'),
     /** The SHARED model handle from install config (e.g., "client", "patient") */
     model: v4_1.z.string(),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skedyul",
-  "version": "0.3.20",
+  "version": "1.0.2",
   "description": "The Skedyul SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",