skedyul 0.1.45 → 0.1.47

package/dist/.build-stamp

@@ -1 +1 @@
-1768782418698
+1768787444775

package/dist/core/client.d.ts

@@ -102,4 +102,108 @@ export declare const communicationChannel: {
      */
     receiveMessage(input: ReceiveMessageInput): Promise<ReceiveMessageResponse>;
 };
+/**
+ * Context required for instance operations.
+ * This is typically extracted from the tool handler's context.
+ */
+export interface InstanceContext {
+    /** The app installation ID for scoping */
+    appInstallationId: string;
+    /** Workplace info */
+    workplace: {
+        id: string;
+    };
+}
+/**
+ * Metadata for an instance.
+ */
+export interface InstanceMeta {
+    modelId: string;
+    label?: string;
+}
+/**
+ * Instance data returned from the API.
+ * Contains field handles as keys with their values.
+ */
+export interface InstanceData {
+    id: string;
+    _meta: InstanceMeta;
+    [fieldHandle: string]: unknown;
+}
+/**
+ * Pagination info for list results.
+ */
+export interface InstancePagination {
+    page: number;
+    total: number;
+    hasMore: boolean;
+    limit: number;
+}
+/**
+ * Result from instance.list().
+ */
+export interface InstanceListResult {
+    data: InstanceData[];
+    pagination: InstancePagination;
+}
+/**
+ * Arguments for instance.list().
+ */
+export interface InstanceListArgs {
+    page?: number;
+    limit?: number;
+    filters?: Record<string, unknown>;
+}
+export declare const instance: {
+    /**
+     * List instances of an internal model scoped by appInstallationId.
+     *
+     * @example
+     * ```ts
+     * const ctx = {
+     *   appInstallationId: fieldContext.appInstallationId,
+     *   workplace: fieldContext.workplace,
+     * }
+     *
+     * const { data: records, pagination } = await instance.list('compliance_record', ctx, {
+     *   page: 1,
+     *   limit: 10,
+     * })
+     * ```
+     */
+    list(modelHandle: string, ctx: InstanceContext, args?: InstanceListArgs): Promise<InstanceListResult>;
+    /**
+     * Get a single instance by ID.
+     *
+     * @example
+     * ```ts
+     * const record = await instance.get('instance-id-123', ctx)
+     * ```
+     */
+    get(id: string, ctx: InstanceContext): Promise<InstanceData | null>;
+    /**
+     * Create a new instance of an internal model.
+     *
+     * @example
+     * ```ts
+     * const newRecord = await instance.create('compliance_record', {
+     *   status: 'pending',
+     *   document_url: 'https://...',
+     * }, ctx)
+     * ```
+     */
+    create(modelHandle: string, data: Record<string, unknown>, ctx: InstanceContext): Promise<InstanceData>;
+    /**
+     * Update an existing instance.
+     *
+     * @example
+     * ```ts
+     * const updated = await instance.update('instance-id-123', {
+     *   status: 'approved',
+     *   bundle_sid: 'BU123456',
+     * }, ctx)
+     * ```
+     */
+    update(id: string, data: Record<string, unknown>, ctx: InstanceContext): Promise<InstanceData>;
+};
 export {};

package/dist/core/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.communicationChannel = exports.workplace = void 0;
+exports.instance = exports.communicationChannel = exports.workplace = void 0;
 exports.configure = configure;
 exports.getConfig = getConfig;
 let config = {
@@ -125,3 +125,88 @@ exports.communicationChannel = {
         return payload;
     },
 };
+exports.instance = {
+    /**
+     * List instances of an internal model scoped by appInstallationId.
+     *
+     * @example
+     * ```ts
+     * const ctx = {
+     *   appInstallationId: fieldContext.appInstallationId,
+     *   workplace: fieldContext.workplace,
+     * }
+     *
+     * const { data: records, pagination } = await instance.list('compliance_record', ctx, {
+     *   page: 1,
+     *   limit: 10,
+     * })
+     * ```
+     */
+    async list(modelHandle, ctx, args) {
+        const payload = (await callCore('instance.list', {
+            modelHandle,
+            appInstallationId: ctx.appInstallationId,
+            workplaceId: ctx.workplace.id,
+            ...(args?.page !== undefined ? { page: args.page } : {}),
+            ...(args?.limit !== undefined ? { limit: args.limit } : {}),
+            ...(args?.filters ? { filters: args.filters } : {}),
+        }));
+        return payload;
+    },
+    /**
+     * Get a single instance by ID.
+     *
+     * @example
+     * ```ts
+     * const record = await instance.get('instance-id-123', ctx)
+     * ```
+     */
+    async get(id, ctx) {
+        const payload = (await callCore('instance.get', {
+            id,
+            appInstallationId: ctx.appInstallationId,
+            workplaceId: ctx.workplace.id,
+        }));
+        return payload.instance;
+    },
+    /**
+     * Create a new instance of an internal model.
+     *
+     * @example
+     * ```ts
+     * const newRecord = await instance.create('compliance_record', {
+     *   status: 'pending',
+     *   document_url: 'https://...',
+     * }, ctx)
+     * ```
+     */
+    async create(modelHandle, data, ctx) {
+        const payload = (await callCore('instance.create', {
+            modelHandle,
+            appInstallationId: ctx.appInstallationId,
+            workplaceId: ctx.workplace.id,
+            data,
+        }));
+        return payload.instance;
+    },
+    /**
+     * Update an existing instance.
+     *
+     * @example
+     * ```ts
+     * const updated = await instance.update('instance-id-123', {
+     *   status: 'approved',
+     *   bundle_sid: 'BU123456',
+     * }, ctx)
+     * ```
+     */
+    async update(id, data, ctx) {
+        const payload = (await callCore('instance.update', {
+            id,
+            appInstallationId: ctx.appInstallationId,
+            workplaceId: ctx.workplace.id,
+            data,
+        }));
+        return payload.instance;
+    },
+};

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export * from './types';
 export * from './schemas';
 export { server } from './server';
 export { z };
-export { workplace, communicationChannel, configure, getConfig } from './core/client';
+export { workplace, communicationChannel, instance, configure, getConfig, } from './core/client';
+export type { InstanceContext, InstanceData, InstanceMeta, InstancePagination, InstanceListResult, InstanceListArgs, } from './core/client';
 declare const _default: {
     z: typeof z;
 };

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONFIG_FILE_NAMES = exports.getAllEnvKeys = exports.getRequiredInstallEnvKeys = exports.validateConfig = exports.loadConfig = exports.defineConfig = exports.getConfig = exports.configure = exports.communicationChannel = exports.workplace = exports.z = exports.server = void 0;
+exports.CONFIG_FILE_NAMES = exports.getAllEnvKeys = exports.getRequiredInstallEnvKeys = exports.validateConfig = exports.loadConfig = exports.defineConfig = exports.getConfig = exports.configure = exports.instance = exports.communicationChannel = exports.workplace = exports.z = exports.server = void 0;
 const zod_1 = require("zod");
 Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
 __exportStar(require("./types"), exports);
@@ -24,6 +24,7 @@ Object.defineProperty(exports, "server", { enumerable: true, get: function () {
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "workplace", { enumerable: true, get: function () { return client_1.workplace; } });
 Object.defineProperty(exports, "communicationChannel", { enumerable: true, get: function () { return client_1.communicationChannel; } });
+Object.defineProperty(exports, "instance", { enumerable: true, get: function () { return client_1.instance; } });
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return client_1.configure; } });
 Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return client_1.getConfig; } });
 // Default export for ESM compatibility when importing from CJS

package/dist/server.js

@@ -310,14 +310,43 @@ function createCallToolHandler(registry, state, onMaxRequests) {
         const originalEnv = { ...process.env };
         Object.assign(process.env, requestEnv);
         try {
-            const inputs = args.inputs ?? {};
-            const functionResult = await fn({
-                input: inputs,
-                context: {
-                    env: process.env,
-                    mode: estimateMode ? 'estimate' : 'execute',
-                },
-            });
+            const rawInputs = (args.inputs ?? {});
+            // Extract context from inputs if present (for field_change/page_action triggers)
+            const inputContext = rawInputs.context;
+            // Create clean inputs without the nested context
+            const cleanInputs = { ...rawInputs };
+            if (inputContext) {
+                delete cleanInputs.context;
+            }
+            // Determine trigger type from input context
+            let trigger = 'agent';
+            if (inputContext?.fieldHandle) {
+                trigger = 'field_change';
+            }
+            else if (inputContext?.fieldValues) {
+                trigger = 'page_action';
+            }
+            else if (inputContext?.trigger) {
+                trigger = inputContext.trigger;
+            }
+            // Build standardized execution context
+            const executionContext = {
+                trigger,
+                appInstallationId: inputContext?.appInstallationId,
+                workplace: inputContext?.workplace,
+                field: inputContext?.fieldHandle
+                    ? {
+                        handle: inputContext.fieldHandle,
+                        type: inputContext.fieldType,
+                        pageHandle: inputContext.pageHandle,
+                    }
+                    : undefined,
+                fieldValues: inputContext?.fieldValues,
+                env: process.env,
+                mode: estimateMode ? 'estimate' : 'execute',
+            };
+            // Call handler with two arguments: (input, context)
+            const functionResult = await fn(cleanInputs, executionContext);
             const billing = normalizeBilling(functionResult.billing);
             return {
                 output: functionResult.output,

package/dist/types.d.ts

@@ -49,10 +49,47 @@ export interface PageActionParams {
     /** Handler context */
     context: PageActionContext;
 }
+/**
+ * @deprecated Use ToolExecutionContext instead. This will be removed in a future version.
+ */
 export interface ToolParams<Input, Output> {
     input: Input;
     context: ToolContext;
 }
+/** Trigger types for tool execution */
+export type ToolTrigger = 'field_change' | 'page_action' | 'agent' | 'workflow';
+/** Field info when tool is triggered by a field change */
+export interface ToolFieldContext {
+    /** Field handle from page definition */
+    handle: string;
+    /** Field datatype */
+    type: string;
+    /** Page handle where the field is defined */
+    pageHandle: string;
+}
+/**
+ * Standardized execution context passed to all tool handlers.
+ * This is injected by the runtime and contains metadata about how the tool was invoked.
+ */
+export interface ToolExecutionContext {
+    /** How the tool was triggered */
+    trigger: ToolTrigger;
+    /** App installation ID for scoping instance operations */
+    appInstallationId?: string;
+    /** Workplace info */
+    workplace?: {
+        id: string;
+        subdomain?: string;
+    };
+    /** Field info (only present for field_change trigger) */
+    field?: ToolFieldContext;
+    /** All current field values on the page (only for page_action trigger) */
+    fieldValues?: Record<string, unknown>;
+    /** Environment variables */
+    env: Record<string, string | undefined>;
+    /** Execution mode - 'estimate' returns billing info without side effects */
+    mode: 'execute' | 'estimate';
+}
 export interface BillingInfo {
     credits: number;
 }
@@ -65,7 +102,14 @@ export interface ToolSchemaWithJson<Schema extends z.ZodTypeAny = z.ZodTypeAny>
     jsonSchema?: Record<string, unknown>;
 }
 export type ToolSchema<Schema extends z.ZodTypeAny = z.ZodTypeAny> = Schema | ToolSchemaWithJson<Schema>;
-export type ToolHandler<Input, Output> = (params: ToolParams<Input, Output>) => Promise<ToolExecutionResult<Output>> | ToolExecutionResult<Output>;
+/**
+ * Tool handler function signature.
+ * Receives tool-specific input as first argument and standardized context as second.
+ *
+ * @param input - Tool-specific input data (validated against inputs schema)
+ * @param context - Standardized execution context injected by runtime
+ */
+export type ToolHandler<Input, Output> = (input: Input, context: ToolExecutionContext) => Promise<ToolExecutionResult<Output>> | ToolExecutionResult<Output>;
 export interface ToolDefinition<Input = unknown, Output = unknown, InputSchema extends z.ZodTypeAny = z.ZodType<Input>, OutputSchema extends z.ZodTypeAny = z.ZodType<Output>> {
     name: string;
     description: string;

package/package.json

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