skedyul 1.2.43 → 1.2.48

package/dist/core/client.d.ts

@@ -253,6 +253,8 @@ export interface InstanceMeta {
  */
 export interface InstanceData {
     id: string;
+    /** The app installation this instance belongs to (if any) */
+    appInstallationId?: string | null;
     _meta: InstanceMeta;
     [fieldHandle: string]: unknown;
 }
@@ -272,116 +274,20 @@ export interface InstanceListArgs {
     /** Filter conditions using StructuredFilter format: { field: { operator: value } } */
     filter?: StructuredFilter;
 }
-export declare const instance: {
-    /**
-     * List instances of an internal model.
-     *
-     * The API token determines the context:
-     * - sk_wkp_ tokens: scoped to the token's app installation
-     * - sk_app_ tokens: searches across ALL installations for the app
-     *
-     * @example
-     * ```ts
-     * // List with filters
-     * const { data, pagination } = await instance.list('compliance_record', {
-     *   filter: { status: 'pending' },
-     *   page: 1,
-     *   limit: 10,
-     * })
-     *
-     * // Cross-installation search (with sk_app_ token)
-     * const { data } = await instance.list('phone_number', {
-     *   filter: { phone: '+1234567890' },
-     * })
-     * ```
-     */
+/**
+ * Interface for instance operations.
+ *
+ * Used by both the global `instance` export (uses current config) and
+ * scoped clients returned by `token.exchange` (bound to specific sk_wkp_ token).
+ */
+export interface InstanceClient {
     list(modelHandle: string, args?: InstanceListArgs): Promise<InstanceListResult>;
-    /**
-     * Get a single instance by ID.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @example
-     * ```ts
-     * const record = await instance.get('phone_number', 'ins_abc123')
-     * ```
-     */
     get(modelHandle: string, id: string): Promise<InstanceData | null>;
-    /**
-     * Create a new instance of an internal model.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @example
-     * ```ts
-     * const newRecord = await instance.create('compliance_record', {
-     *   status: 'pending',
-     *   document_url: 'https://...',
-     * })
-     * ```
-     */
     create(modelHandle: string, data: Record<string, unknown>): Promise<InstanceData>;
-    /**
-     * Update an existing instance.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @example
-     * ```ts
-     * const updated = await instance.update('compliance_record', 'ins_abc123', {
-     *   status: 'approved',
-     *   bundle_sid: 'BU123456',
-     * })
-     * ```
-     */
     update(modelHandle: string, id: string, data: Record<string, unknown>): Promise<InstanceData>;
-    /**
-     * Delete an existing instance.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @example
-     * ```ts
-     * const { deleted } = await instance.delete('phone_number', 'ins_abc123')
-     * ```
-     */
     delete(modelHandle: string, id: string): Promise<{
         deleted: boolean;
     }>;
-    /**
-     * Delete multiple instances of an internal model in a single batch operation.
-     *
-     * This is more efficient than calling delete() multiple times as it reduces
-     * API overhead and executes all deletes in a single transaction.
-     *
-     * Supports two modes:
-     * - **By IDs**: Delete specific instances by their IDs
-     * - **By Filter**: Delete instances matching a StructuredFilter
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @param modelHandle - The model handle from provision config
-     * @param options - Either { ids: string[] } or { filter: StructuredFilter }
-     * @returns Object containing deleted instance IDs and any errors that occurred
-     *
-     * @example
-     * ```ts
-     * // Delete by IDs
-     * const { deleted, errors } = await instance.deleteMany('panel_result', {
-     *   ids: ['ins_abc123', 'ins_def456'],
-     * })
-     *
-     * // Delete by filter
-     * const { deleted, errors } = await instance.deleteMany('panel_result', {
-     *   filter: { status: { eq: 'pending' } },
-     * })
-     *
-     * if (errors.length > 0) {
-     *   console.log('Some items failed:', errors)
-     * }
-     * console.log('Deleted:', deleted.length, 'instances')
-     * ```
-     */
     deleteMany(modelHandle: string, options: {
         ids: string[];
     } | {
@@ -393,31 +299,6 @@ export declare const instance: {
             error: string;
         }>;
     }>;
-    /**
-     * Create multiple instances of an internal model in a single batch operation.
-     *
-     * This is more efficient than calling create() multiple times as it reduces
-     * API overhead and executes all creates in a single transaction.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @param modelHandle - The model handle from provision config
-     * @param items - Array of data objects to create as instances
-     * @returns Object containing created instances and any errors that occurred
-     *
-     * @example
-     * ```ts
-     * const { created, errors } = await instance.createMany('panel_result', [
-     *   { test_name: 'Glucose', value_string: '5.2', unit: 'mmol/L' },
-     *   { test_name: 'Creatinine', value_string: '80', unit: 'umol/L' },
-     * ])
-     *
-     * if (errors.length > 0) {
-     *   console.log('Some items failed:', errors)
-     * }
-     * console.log('Created:', created.length, 'instances')
-     * ```
-     */
     createMany(modelHandle: string, items: Record<string, unknown>[]): Promise<{
         created: InstanceData[];
         errors: Array<{
@@ -425,31 +306,6 @@ export declare const instance: {
             error: string;
         }>;
     }>;
-    /**
-     * Update multiple instances of an internal model in a single batch operation.
-     *
-     * This is more efficient than calling update() multiple times as it reduces
-     * API overhead and executes all updates in a single transaction.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @param modelHandle - The model handle from provision config
-     * @param items - Array of objects containing id and data to update
-     * @returns Object containing updated instances and any errors that occurred
-     *
-     * @example
-     * ```ts
-     * const { updated, errors } = await instance.updateMany('panel_result', [
-     *   { id: 'ins_abc123', data: { value_string: '5.5' } },
-     *   { id: 'ins_def456', data: { value_string: '85' } },
-     * ])
-     *
-     * if (errors.length > 0) {
-     *   console.log('Some items failed:', errors)
-     * }
-     * console.log('Updated:', updated.length, 'instances')
-     * ```
-     */
     updateMany(modelHandle: string, items: Array<{
         id: string;
         data: Record<string, unknown>;
@@ -460,118 +316,91 @@ export declare const instance: {
             error: string;
         }>;
     }>;
-    /**
-     * Upsert multiple instances of an internal model in a single batch operation.
-     *
-     * Creates instances if they don't exist, updates them if they do (based on matchField).
-     * This is more efficient than calling upsert() multiple times as it reduces
-     * API overhead and executes all upserts in a single transaction.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
-     *
-     * @param modelHandle - The model handle from provision config
-     * @param items - Array of data objects to upsert as instances
-     * @param matchField - The field handle to match existing instances (e.g., 'vetnostics_id')
-     * @returns Object containing upserted instances with mode and any errors that occurred
-     *
-     * @example
-     * ```ts
-     * const { results, errors } = await instance.upsertMany('panel_result', [
-     *   { vetnostics_id: '25-54966975/622/glucose', test_name: 'Glucose', value_string: '5.2' },
-     *   { vetnostics_id: '25-54966975/622/creatinine', test_name: 'Creatinine', value_string: '80' },
-     * ], 'vetnostics_id')
-     *
-     * if (errors.length > 0) {
-     *   console.log('Some items failed:', errors)
-     * }
-     * const created = results.filter(r => r.mode === 'created')
-     * const updated = results.filter(r => r.mode === 'updated')
-     * console.log('Created:', created.length, 'Updated:', updated.length)
-     * ```
-     */
     upsertMany(modelHandle: string, items: Record<string, unknown>[], matchField: string): Promise<{
         results: Array<InstanceData & {
-            mode: "created" | "updated";
+            mode: 'created' | 'updated';
         }>;
         errors: Array<{
             index: number;
             error: string;
         }>;
     }>;
+    isConfigured(modelHandle: string): Promise<boolean>;
+    getConfiguredModels(modelHandles: string[]): Promise<Map<string, boolean>>;
+}
+/**
+ * Create an instance client with a specific configuration.
+ *
+ * This is useful for creating clients bound to specific tokens (e.g., from token.exchange).
+ * All methods on the returned client use the provided configuration.
+ *
+ * @param config - Client configuration with baseUrl and apiToken
+ * @returns InstanceClient bound to the provided config
+ *
+ * @example
+ * ```ts
+ * // After getting a scoped token via token.exchange
+ * const scopedClient = createInstanceClient({
+ *   baseUrl: getConfig().baseUrl,
+ *   apiToken: scopedToken,
+ * })
+ * await scopedClient.create('studio', { ... })
+ * ```
+ */
+export declare function createInstanceClient(config: ClientConfig): InstanceClient;
+export declare const instance: InstanceClient;
+export declare const token: {
     /**
-     * Check if a model is configured (linked) for the current app installation.
+     * Exchange an sk_app_ or sk_prv_ token for an installation-scoped InstanceClient.
      *
-     * This is useful for best-effort sync scenarios where you want to check
-     * which models are available before attempting to create instances.
+     * **Requires sk_app_ or sk_prv_ token** - works with app-level or provision tokens.
+     * Used by developer tools after discovering `appInstallationId` from a record.
      *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
+     * Returns an InstanceClient bound to the installation's sk_wkp_ token.
+     * All CRM writes should use this scoped client.
      *
-     * @param modelHandle - The model handle from provision config
-     * @returns true if the model is configured and has a valid targetId, false otherwise
+     * The underlying JWT is short-lived (1 hour) and scoped to the specific installation.
      *
      * @example
      * ```ts
-     * // Check if models are configured before syncing
-     * const isTestOrderConfigured = await instance.isConfigured('test_order')
-     * const isTestReportConfigured = await instance.isConfigured('test_report')
-     *
-     * if (isTestOrderConfigured) {
-     *   await instance.create('test_order', orderData)
+     * // Developer tool: discover → exchange → write
+     * const accessRequest = await instance.get('access_request', id) // uses sk_prv_
+     * if (!accessRequest?.appInstallationId) {
+     *   throw new Error('Access request missing appInstallationId')
      * }
-     * ```
-     */
-    isConfigured(modelHandle: string): Promise<boolean>;
-    /**
-     * Check which models from a list are configured for the current app installation.
-     *
-     * This is more efficient than calling isConfigured() multiple times as it
-     * makes a single API call to check all models at once.
-     *
-     * The API token determines the context (app installation is embedded in sk_wkp_ tokens).
      *
-     * @param modelHandles - Array of model handles from provision config
-     * @returns Map of model handle to configuration status
+     * // Exchange for a scoped instance client
+     * const scopedInstance = await token.exchange(accessRequest.appInstallationId)
      *
-     * @example
-     * ```ts
-     * // Check multiple models at once
-     * const configStatus = await instance.getConfiguredModels([
-     *   'test_order',
-     *   'test_report',
-     *   'panel_result',
-     *   'culture_result',
-     * ])
-     *
-     * if (configStatus.get('test_order')) {
-     *   // test_order is configured
-     * }
+     * // All writes use the scoped client (sk_wkp_ internally)
+     * await scopedInstance.create('studio', { ... })
+     * await scopedInstance.update('access_request', id, { status: 'APPROVED' })
      * ```
      */
-    getConfiguredModels(modelHandles: string[]): Promise<Map<string, boolean>>;
-};
-export declare const token: {
+    exchange(appInstallationId: string): Promise<InstanceClient>;
     /**
-     * Exchange an sk_app_ token for an installation-scoped sk_wkp_ JWT.
+     * Exchange an sk_app_ or sk_prv_ token for a raw installation-scoped JWT.
      *
-     * **Requires sk_app_ token** - only works with app-level tokens.
-     * Used after identifying the target installation (e.g., via instance.search).
+     * **Requires sk_app_ or sk_prv_ token** - works with app-level or provision tokens.
+     * For most use cases, prefer `token.exchange()` which returns a ready-to-use InstanceClient.
      *
-     * The returned JWT is short-lived (1 hour) and scoped to the specific installation.
+     * Use this when you need the raw token string (e.g., for passing to external services,
+     * storing for later use, or advanced scenarios requiring manual config management).
      *
      * @example
      * ```ts
-     * // After finding the installation via instance.search
-     * const { token: scopedToken } = await token.exchange(appInstallationId)
+     * // Get raw token for advanced use cases
+     * const { token: scopedToken, appInstallationId } = await token.exchangeRaw(installId)
      *
-     * // Use the scoped token for subsequent operations
+     * // Manual config management
      * runWithConfig({ apiToken: scopedToken, baseUrl: config.baseUrl }, async () => {
-     *   const channels = await communicationChannel.list({ filter: { identifierValue: phoneNumber } })
-     *   // ...
+     *   await communicationChannel.list({ filter: { ... } })
      * })
      * ```
      */
-    exchange(appInstallationId: string): Promise<{
+    exchangeRaw(appInstallationId: string): Promise<{
         token: string;
+        appInstallationId: string;
     }>;
 };
 /**
@@ -809,6 +638,133 @@ export declare const webhook: {
         webhooks: WebhookListItem[];
     }>;
 };
+/**
+ * Parameters for cron.subscribe
+ */
+export interface CronSubscribeParams {
+    /** Name of the tool to invoke */
+    toolName: string;
+    /** Cron schedule expression (e.g., "0/20 9-17 * * 1-5") */
+    schedule: string;
+    /** Timezone for the schedule (e.g., "America/New_York"). Defaults to UTC. */
+    timezone?: string;
+    /** Inputs to pass to the tool on each invocation */
+    inputs?: Record<string, unknown>;
+    /** Key for cursor sharing (defaults to toolName if not specified) */
+    cursorKey?: string;
+    /** Optional human-friendly label */
+    label?: string;
+}
+/**
+ * Response from cron.subscribe
+ */
+export interface CronSubscribeResult {
+    /** Subscription ID */
+    id: string;
+    /** Name of the tool to invoke */
+    toolName: string;
+    /** Schedule expression */
+    schedule: string;
+    /** Timezone for the schedule */
+    timezone: string;
+}
+/**
+ * Cron subscription info returned from cron.list
+ */
+export interface CronSubscriptionItem {
+    /** Subscription ID */
+    id: string;
+    /** Name of the tool to invoke */
+    toolName: string;
+    /** Schedule expression */
+    schedule: string;
+    /** Timezone for the schedule */
+    timezone: string;
+    /** Whether this subscription is enabled */
+    enabled: boolean;
+    /** Inputs passed to the tool */
+    inputs: Record<string, unknown> | null;
+    /** Key for cursor sharing */
+    cursorKey: string | null;
+    /** Human-friendly label */
+    label: string | null;
+    /** ISO timestamp when created */
+    createdAt: string;
+}
+/**
+ * Options for cron.list
+ */
+export interface CronListOptions {
+    /** Filter by tool name */
+    toolName?: string;
+}
+export declare const cron: {
+    /**
+     * Subscribe to run a tool on a schedule.
+     *
+     * Creates a cron subscription that will invoke the specified tool
+     * at the given schedule. Multiple subscriptions can share cursor
+     * state via the cursorKey parameter.
+     *
+     * **Requires sk_wkp_ token** - subscriptions are scoped to the app installation.
+     *
+     * @example
+     * ```ts
+     * // Work hours: sync every 20 mins
+     * await cron.subscribe({
+     *   toolName: 'sync_lab_results',
+     *   schedule: '0,20,40 9-17 * * 1-5',  // 9am-5pm Mon-Fri
+     *   timezone: 'America/New_York',
+     *   inputs: { source: 'vetnostics' },
+     *   label: 'Work hours sync',
+     * })
+     *
+     * // After hours: sync every 3 hours (shares cursor with work hours)
+     * await cron.subscribe({
+     *   toolName: 'sync_lab_results',
+     *   schedule: '0 0,3,6,9,12,15,18,21 * * *',
+     *   timezone: 'America/New_York',
+     *   inputs: { source: 'vetnostics' },
+     *   label: 'After hours sync',
+     * })
+     * ```
+     */
+    subscribe(params: CronSubscribeParams): Promise<CronSubscribeResult>;
+    /**
+     * Unsubscribe from a cron subscription.
+     *
+     * Stops the scheduled tool invocation and deletes the subscription.
+     *
+     * @param subscriptionId - The subscription ID to delete
+     * @returns Whether the subscription was deleted (false if not found)
+     *
+     * @example
+     * ```ts
+     * const { deleted } = await cron.unsubscribe('crsub_abc123')
+     * ```
+     */
+    unsubscribe(subscriptionId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * List cron subscriptions for this installation.
+     *
+     * @param options - Optional filter by tool name
+     * @returns Array of cron subscriptions
+     *
+     * @example
+     * ```ts
+     * // List all subscriptions
+     * const { subscriptions } = await cron.list()
+     *
+     * // List subscriptions for a specific tool
+     * const { subscriptions } = await cron.list({ toolName: 'sync_lab_results' })
+     * ```
+     */
+    list(options?: CronListOptions): Promise<{
+        subscriptions: CronSubscriptionItem[];
+    }>;
+};
 /**
  * Parameters for resource.link
  */