skedyul 0.1.12 → 0.1.14

package/README.md

@@ -60,27 +60,76 @@ For integration-specific RPCs that belong to your platform rather than a tool, p
 
 The MCP server exposes `POST /core` (with `{ method, params }`) and `POST /core/webhook` for these operations. They never appear under `tools/list` unlesstaken explicit MCP tooling—they are separate transport-level handlers and do not count against tool request limits. Make sure your service returns the structured channel/message data defined in `src/core/types.ts` so the responses stay consistent, and guard `/core`/`/core/webhook` with your platform’s preferred authentication if you surface them externally.
 
-## Higher-level helpers
+## Core API Client
 
-While `server.create` hosts the MCP surface, `skedyul.workplace` and `skedyul.communicationChannel` expose dedicated helpers that talk to `/core` for the same workplace and channel metadata. Each helper returns the typed objects defined in `src/core/types.ts` so integrations can look up a channel/workplace pair before acting on an incoming webhook without manually composing the RPC payload or dealing with authentication.
+The SDK includes a client for the Skedyul Core API that enables lookups across workplaces. This is especially useful in webhook handlers where you need to identify which workspace a request belongs to.
 
-The helpers currently provide:
+### Configuration
 
-- `workplace.list(filter?: Record<string, unknown>)`
-- `workplace.get(id: string)`
-- `communicationChannel.list(filter?: Record<string, unknown>)`
-- `communicationChannel.get(id: string)`
+Configure the client using environment variables or programmatically:
 
-Example:
+**Environment Variables:**
+
+```bash
+# Base URL for the Skedyul Core API
+SKEDYUL_API_URL=https://app.skedyul.com/api
+
+# Your API token (App API or Workplace API)
+SKEDYUL_API_TOKEN=sk_app_xxxxx
+```
+
+**Programmatic Configuration:**
+
+```ts
+import { configure } from 'skedyul'
+
+configure({
+  baseUrl: 'https://app.skedyul.com/api',
+  apiToken: 'sk_app_xxxxx',
+})
+```
+
+### Token Types
+
+- **App API Token (`sk_app_*`)**: Grants access to all workplaces where your app is installed. Use this for webhooks where you need to look up resources across workplaces.
+- **Workplace API Token (`sk_wkp_*`)**: Scoped to a single workplace. Use this when you know the target workspace (e.g., MCP tools).
+
+### Available Methods
+
+- `workplace.list({ filter?, limit? })` - List workplaces
+- `workplace.get(id)` - Get a single workplace
+- `communicationChannel.list({ filter?, limit? })` - List communication channels
+- `communicationChannel.get(id)` - Get a single channel
+
+### Example: Webhook Handler
 
 ```ts
-import { communicationChannel, workplace } from 'skedyul'
+import { communicationChannel, configure } from 'skedyul'
 
-const [channel] = await communicationChannel.list({
-  filter: { identifierValue: '+15551234567' },
+// Configure once at startup (or use env vars)
+configure({
+  baseUrl: process.env.SKEDYUL_API_URL,
+  apiToken: process.env.SKEDYUL_API_TOKEN,
 })
 
-const owner = await workplace.get(channel.workplaceId)
+// In your webhook handler
+async function handleIncomingMessage(phoneNumber: string) {
+  // Find the channel across all workplaces where your app is installed
+  const channels = await communicationChannel.list({
+    filter: { identifierValue: phoneNumber },
+    limit: 1,
+  })
+
+  if (channels.length === 0) {
+    throw new Error('No channel found for this phone number')
+  }
+
+  const channel = channels[0]
+  console.log(`Found channel in workplace: ${channel.workplaceId}`)
+
+  // Now you can process the message in the correct workspace context
+  return channel
+}
 ```
 
 Use these helpers for internal wiring—like pulling the correct workplace for a webhook—without touching the MCP tooling surface directly.

package/dist/cli/commands/validate.js

@@ -163,7 +163,7 @@ async function validateCommand(args) {
         }
     }
     // Check if workflows directory exists
-    const workflowsPath = config.workflows || './workflows';
+    const workflowsPath = config.workflowsPath || './workflows';
     const absoluteWorkflowsPath = path.resolve(path.dirname(configPath), workflowsPath);
     if (!fs.existsSync(absoluteWorkflowsPath)) {
         warnings.push(`Workflows directory not found: ${workflowsPath}`);
@@ -178,7 +178,7 @@ async function validateCommand(args) {
             version: config.version,
             computeLayer: config.computeLayer,
             tools: config.tools,
-            workflows: config.workflows,
+            workflowsPath: config.workflowsPath,
             globalEnvKeys: envKeys.global,
             installEnvKeys: envKeys.install,
             requiredInstallEnvKeys: requiredInstallKeys,

package/dist/config.d.ts

@@ -35,6 +35,98 @@ export interface InstallConfig {
      */
     appModels?: AppModelDefinition[];
 }
+export interface AppFieldVisibility {
+    /** Show in data/detail view */
+    data?: boolean;
+    /** Show in list view */
+    list?: boolean;
+    /** Show in filters */
+    filters?: boolean;
+}
+export interface AppFieldDefinition {
+    /** Human-readable label */
+    label: string;
+    /** Field handle/key */
+    fieldHandle: string;
+    /** Entity this field belongs to (e.g., 'contact') */
+    entityHandle: string;
+    /** Metafield definition handle */
+    definitionHandle: string;
+    /** Whether this field is required */
+    required?: boolean;
+    /** Whether this is a system field */
+    system?: boolean;
+    /** Whether values must be unique */
+    unique?: boolean;
+    /** Default value */
+    defaultValue?: {
+        value: unknown;
+    };
+    /** Visibility settings */
+    visibility?: AppFieldVisibility;
+}
+export interface ChannelToolBindings {
+    /** Tool name for sending messages on this channel */
+    send_message: string;
+}
+export type ChannelIdentifierType = 'DEDICATED_PHONE' | 'TEXT' | 'EMAIL';
+export interface ChannelIdentifierValue {
+    /** Type of identifier */
+    type: ChannelIdentifierType;
+    /** Metafield definition handle for the identifier */
+    definitionHandle: string;
+}
+export interface CommunicationChannelDefinition {
+    /** Unique handle for this channel type (e.g., 'sms', 'email') */
+    handle: string;
+    /** Human-readable name */
+    name: string;
+    /** Icon for UI (lucide icon name) */
+    icon?: string;
+    /** Tool bindings for this channel */
+    tools: ChannelToolBindings;
+    /** How the channel identifier is configured */
+    identifierValue: ChannelIdentifierValue;
+    /** Fields to add to contacts when using this channel */
+    appFields?: AppFieldDefinition[];
+    /** Additional settings UI */
+    settings?: unknown[];
+}
+export interface WorkflowActionInput {
+    /** Input key */
+    key: string;
+    /** Human-readable label */
+    label: string;
+    /** Reference to a field */
+    fieldRef?: {
+        fieldHandle: string;
+        entityHandle: string;
+    };
+    /** Template string for the input */
+    template?: string;
+}
+export interface WorkflowAction {
+    /** Human-readable label */
+    label: string;
+    /** Action handle/key */
+    handle: string;
+    /** Whether this action supports batch execution */
+    batch?: boolean;
+    /** Entity this action operates on */
+    entityHandle?: string;
+    /** Input definitions for this action */
+    inputs?: WorkflowActionInput[];
+}
+export interface WorkflowDefinition {
+    /** Human-readable label */
+    label: string;
+    /** Workflow handle/key */
+    handle: string;
+    /** Which channel handle this workflow is associated with (optional) */
+    channelHandle?: string;
+    /** Actions in this workflow */
+    actions: WorkflowAction[];
+}
 export type ComputeLayerType = 'serverless' | 'dedicated';
 export interface SkedyulConfig {
     /** App name */
@@ -48,7 +140,7 @@ export interface SkedyulConfig {
     /** Path to the tool registry file (default: './src/registry.ts') */
     tools?: string;
     /** Path to the workflows directory (default: './workflows') */
-    workflows?: string;
+    workflowsPath?: string;
     /**
      * Global/version-level environment variables.
      * These are baked into the container and are the same for all installations.
@@ -60,6 +152,16 @@ export interface SkedyulConfig {
      * Defines what users need to configure when installing the app.
      */
     install?: InstallConfig;
+    /**
+     * Communication channels this app provides.
+     * Defines how the app can send/receive messages.
+     */
+    communicationChannels?: CommunicationChannelDefinition[];
+    /**
+     * Workflows this app provides.
+     * Can reference channels via channelHandle.
+     */
+    workflows?: WorkflowDefinition[];
 }
 /**
  * Define a Skedyul app configuration with full type safety.

package/dist/config.js

@@ -206,6 +206,42 @@ function validateConfig(config) {
             }
         }
     }
+    // Validate communicationChannels
+    if (config.communicationChannels) {
+        for (let i = 0; i < config.communicationChannels.length; i++) {
+            const channel = config.communicationChannels[i];
+            if (!channel.handle) {
+                errors.push(`communicationChannels[${i}]: Missing required field 'handle'`);
+            }
+            if (!channel.name) {
+                errors.push(`communicationChannels[${i}]: Missing required field 'name'`);
+            }
+            if (!channel.tools?.send_message) {
+                errors.push(`communicationChannels[${i}]: Missing required field 'tools.send_message'`);
+            }
+            if (!channel.identifierValue?.type) {
+                errors.push(`communicationChannels[${i}]: Missing required field 'identifierValue.type'`);
+            }
+            if (!channel.identifierValue?.definitionHandle) {
+                errors.push(`communicationChannels[${i}]: Missing required field 'identifierValue.definitionHandle'`);
+            }
+        }
+    }
+    // Validate workflows
+    if (config.workflows) {
+        for (let i = 0; i < config.workflows.length; i++) {
+            const workflow = config.workflows[i];
+            if (!workflow.handle) {
+                errors.push(`workflows[${i}]: Missing required field 'handle'`);
+            }
+            if (!workflow.label) {
+                errors.push(`workflows[${i}]: Missing required field 'label'`);
+            }
+            if (!workflow.actions || workflow.actions.length === 0) {
+                errors.push(`workflows[${i}]: Must have at least one action`);
+            }
+        }
+    }
     return { valid: errors.length === 0, errors };
 }
 /**

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export * from './types';
 export { server } from './server';
 export { workplace, communicationChannel } from './core/client';
 export { defineConfig, loadConfig, validateConfig, getRequiredInstallEnvKeys, getAllEnvKeys, CONFIG_FILE_NAMES, } from './config';
-export type { SkedyulConfig, EnvVariableDefinition, EnvSchema, EnvVisibility, InstallConfig, AppModelDefinition, ComputeLayerType, } from './config';
+export type { SkedyulConfig, EnvVariableDefinition, EnvSchema, EnvVisibility, InstallConfig, AppModelDefinition, ComputeLayerType, AppFieldVisibility, AppFieldDefinition, ChannelToolBindings, ChannelIdentifierType, ChannelIdentifierValue, CommunicationChannelDefinition, WorkflowActionInput, WorkflowAction, WorkflowDefinition, } from './config';

package/package.json

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