@uniformdev/automations-sdk 20.50.2-alpha.109 → 20.50.2-alpha.149

package/dist/ai/index.d.mts

@@ -1,6 +1,24 @@
 import { ApiClient, ClientOptions } from '@uniformdev/context/api';
 import { UIMessage } from 'ai';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * Contract for a structured Scout result: a zod schema, or a plain JSON
+ * Schema object passed through verbatim.
+ */
+type ScoutOutputSchema = StandardSchemaV1 | Record<string, unknown>;
+/**
+ * Infers the structured-result type from a {@link ScoutOutputSchema}: a zod schema yields its
+ * inferred output type; a raw JSON Schema object yields `unknown` (no static type information).
+ */
+type InferStructuredOutput<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
+
+/**
+ * User turn for {@link ScoutClient.invoke}. `id` is optional — a UUID is generated when omitted.
+ */
+type ScoutInvokeMessage = Omit<UIMessage, 'id'> & {
+    id?: string;
+};
 /**
  * Options for {@link ScoutClient}.
  *
@@ -16,30 +34,49 @@ interface ScoutClientOptions extends ClientOptions {
      */
     aiApiHost?: string;
 }
-/** Parameters for a Scout invocation. */
-interface ScoutInvokeParams {
+/** Shared invoke parameters. */
+interface ScoutInvokeParamsCommon {
     /**
-     * Stable thread id this turn belongs to. The caller owns it: generate one (e.g. `crypto.randomUUID()`)
-     * for a one-shot invocation, or reuse the same id across calls to continue a multi-turn conversation
-     * (history is kept server-side per thread).
+     * Thread this turn belongs to. Omit for a one-shot turn (a new thread id is generated).
+     * Reuse the same id across calls to continue a multi-turn conversation.
      */
-    threadId: string;
+    threadId?: string;
     /**
-     * Conversation messages in the Vercel AI SDK {@link UIMessage} shape. The server takes the
-     * trailing entry as the new user turn; prior history is kept server-side per thread, so
-     * multi-turn callers can send just the new message.
+     * The new user turn for this invocation. A string is shorthand for a user message with a single
+     * text part.
      */
-    messages: UIMessage[];
+    message: string | ScoutInvokeMessage;
+}
+/** Parameters for a Scout invocation. */
+interface ScoutInvokeParams<S extends ScoutOutputSchema = ScoutOutputSchema> extends ScoutInvokeParamsCommon {
+    /**
+     * Optional schema for a structured result — a zod schema (preferred; it also types
+     * {@link ScoutInvokeCompletedResult.structuredOutput}) or a plain JSON Schema object. When provided,
+     * Scout must record a result conforming to it as its final action; {@link ScoutClient.invoke} throws
+     * if Scout completes without recording structured output. Throws if the team is out of AI credits.
+     */
+    outputSchema?: S;
+}
+/** Parameters for a Scout invocation without structured output. */
+interface ScoutInvokeParamsWithoutOutputSchema extends ScoutInvokeParamsCommon {
+    outputSchema?: undefined;
 }
-/** Aggregated result of {@link ScoutClient.invoke}. */
+/** Parameters for a Scout invocation with structured output. */
+interface ScoutInvokeParamsWithOutputSchema<S extends ScoutOutputSchema = ScoutOutputSchema> extends ScoutInvokeParamsCommon {
+    outputSchema: S;
+}
+/** Result of {@link ScoutClient.invoke} when no `outputSchema` was passed. */
 interface ScoutInvokeResult {
-    /** `completed` on success; `over-credit-limit` when the team is out of AI credits. */
-    outcome: 'completed' | 'skipped' | 'over-credit-limit';
     /** The final assistant message text. */
     text: string;
     /** The full thread messages after the turn (UI message shape). */
     messages: UIMessage[];
 }
+/** Result when an `outputSchema` was passed and Scout completed the turn. */
+interface ScoutInvokeCompletedResult<TStructured> extends ScoutInvokeResult {
+    /** Structured result conforming to the supplied `outputSchema`. */
+    structuredOutput: TStructured;
+}
 /**
  * The raw HTTP request details for the headless Scout endpoint, for callers that want to drive
  * the request themselves (e.g. hand to a streaming transport). See {@link ScoutClient.getRequest}.
@@ -61,8 +98,7 @@ interface ScoutRequest {
  *
  * const scout = new ScoutClient(context.uniformCredentials);
  * const { text } = await scout.invoke({
- *   threadId: crypto.randomUUID(),
- *   messages: [{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Review this entry for brand tone.' }] }],
+ *   message: 'Review this entry for brand tone.',
  * });
  * ```
  */
@@ -79,9 +115,12 @@ declare class ScoutClient extends ApiClient<ScoutClientOptions> {
      * [Vercel AI SDK UI message stream](https://sdk.vercel.ai) backend when called with
      * `Accept: text/event-stream`, so point the AI SDK's transport / `readUIMessageStream` at it.
      *
-     * @param params - The thread id and the conversation messages for this turn.
+     * @param params - The user message for this turn and optional thread id. Pass `outputSchema`
+     * (a zod schema or JSON Schema object) to also receive a structured result conforming to it; with a
+     * zod schema, `structuredOutput` is typed accordingly. Throws if the team is out of AI credits.
      */
-    invoke(params: ScoutInvokeParams): Promise<ScoutInvokeResult>;
+    invoke(params: ScoutInvokeParamsWithoutOutputSchema): Promise<ScoutInvokeResult>;
+    invoke<S extends ScoutOutputSchema>(params: ScoutInvokeParamsWithOutputSchema<S>): Promise<ScoutInvokeCompletedResult<InferStructuredOutput<S>>>;
     /**
      * Returns the endpoint URL + auth headers for a thread's headless Scout endpoint, so you can
      * drive the request yourself.
@@ -105,4 +144,4 @@ declare class ScoutClient extends ApiClient<ScoutClientOptions> {
     getRequest(threadId: string): ScoutRequest;
 }
 
-export { ScoutClient, type ScoutClientOptions, type ScoutInvokeParams, type ScoutInvokeResult, type ScoutRequest };
+export { ScoutClient, type ScoutClientOptions, type ScoutInvokeCompletedResult, type ScoutInvokeMessage, type ScoutInvokeParams, type ScoutInvokeParamsCommon, type ScoutInvokeParamsWithOutputSchema, type ScoutInvokeParamsWithoutOutputSchema, type ScoutInvokeResult, type ScoutRequest };

package/dist/ai/index.mjs

@@ -7,6 +7,28 @@ import {
 
 // src/ai/ScoutClient.ts
 import { ApiClient } from "@uniformdev/context/api";
+
+// src/ai/toOutputJsonSchema.ts
+import { toJSONSchema } from "zod/v4/core";
+function isZodSchema(value) {
+  return typeof value === "object" && value !== null && "_zod" in value;
+}
+function isStandardSchema(value) {
+  return typeof value === "object" && value !== null && "~standard" in value;
+}
+function toOutputJsonSchema(schema) {
+  if (isZodSchema(schema)) {
+    return toJSONSchema(schema);
+  }
+  if (isStandardSchema(schema)) {
+    throw new Error(
+      "`outputSchema` is a Standard Schema but not a zod schema. Conversion to JSON Schema currently supports zod only \u2014 provide a zod schema or a JSON Schema object."
+    );
+  }
+  return schema;
+}
+
+// src/ai/ScoutClient.ts
 var DEFAULT_AI_HOST = "https://ai.uniform.global";
 var _aiApiHost, _ScoutClient_instances, endpoint_fn;
 var ScoutClient = class extends ApiClient {
@@ -17,23 +39,28 @@ var ScoutClient = class extends ApiClient {
     __privateAdd(this, _aiApiHost);
     __privateSet(this, _aiApiHost, ((_a = options.aiApiHost) != null ? _a : DEFAULT_AI_HOST).replace(/\/+$/, ""));
   }
-  /**
-   * Invokes Scout and returns the aggregated result once the turn completes.
-   *
-   * This is the right fit for automations and other headless callers, where no user is watching
-   * output stream in. If you do need to forward incremental output to a chat surface (a Slack
-   * relay, a browser `useChat` app), don't reach for a bespoke client — the endpoint at
-   * `POST {aiApiHost}/projects/:projectId/threads/:threadId/messages` is a standard
-   * [Vercel AI SDK UI message stream](https://sdk.vercel.ai) backend when called with
-   * `Accept: text/event-stream`, so point the AI SDK's transport / `readUIMessageStream` at it.
-   *
-   * @param params - The thread id and the conversation messages for this turn.
-   */
   async invoke(params) {
-    return this.apiClient(new URL(__privateMethod(this, _ScoutClient_instances, endpoint_fn).call(this, params.threadId)), {
-      method: "POST",
-      body: JSON.stringify({ messages: params.messages })
-    });
+    var _a;
+    const threadId = (_a = params.threadId) != null ? _a : crypto.randomUUID();
+    const messages = [normalizeInvokeMessage(params.message)];
+    const outputSchema = params.outputSchema ? toOutputJsonSchema(params.outputSchema) : void 0;
+    const result = await this.apiClient(
+      new URL(__privateMethod(this, _ScoutClient_instances, endpoint_fn).call(this, threadId)),
+      {
+        method: "POST",
+        body: JSON.stringify({ messages, outputSchema })
+      }
+    );
+    if (result.outcome === "over-credit-limit") {
+      throw new Error("Scout is out of AI credits for this team.");
+    }
+    if (params.outputSchema && result.structuredOutput == null) {
+      throw new Error("Scout finished without recording structured output.");
+    }
+    if (params.outputSchema) {
+      return result;
+    }
+    return result;
   }
   /**
    * Returns the endpoint URL + auth headers for a thread's headless Scout endpoint, so you can
@@ -73,6 +100,13 @@ endpoint_fn = function(threadId) {
     __privateGet(this, _aiApiHost)
   ).toString();
 };
+function normalizeInvokeMessage(message) {
+  var _a;
+  if (typeof message === "string") {
+    return { id: crypto.randomUUID(), role: "user", parts: [{ type: "text", text: message }] };
+  }
+  return { ...message, id: (_a = message.id) != null ? _a : crypto.randomUUID() };
+}
 export {
   ScoutClient
 };

package/dist/api/index.d.mts

@@ -9,7 +9,12 @@ interface paths$2 {
             path?: never;
             cookie?: never;
         };
-        /** @description Returns the log entries for a single automation run. */
+        /**
+         * @deprecated
+         * @description Returns the log entries for a single automation run.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
         get: {
             parameters: {
                 query: {
@@ -156,7 +161,12 @@ interface paths$1 {
             path?: never;
             cookie?: never;
         };
-        /** @description Lists automation runs for a project, optionally filtered by automation and status. */
+        /**
+         * @deprecated
+         * @description Lists automation runs for a project, optionally filtered by automation and status.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
         get: {
             parameters: {
                 query: {
@@ -225,7 +235,64 @@ interface paths$1 {
             };
         };
         put?: never;
-        post?: never;
+        /**
+         * @deprecated
+         * @description Triggers a one-off run of a scheduled automation, for testing.
+         *
+         *     The run is identical to a real scheduled occurrence (same trigger context, no input, same machine
+         *     identity) but is enqueued out of band: it does not advance the automation's schedule, and runs even
+         *     when the automation is disabled. Only `schedule`-triggered automations can be run this way — other
+         *     trigger types have a natural way to exercise them (fire the event, send the webhook, invoke the tool).
+         *
+         *     The caller must hold every role the automation's identity holds (or be a team admin), since the run
+         *     acts as that identity.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The project ID. */
+                        projectId: string;
+                        /** @description The automation public ID. */
+                        publicId: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description 202 response */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description ID of the enqueued run; poll the runs list to see its outcome. */
+                            runId: string;
+                        };
+                    };
+                };
+                400: components$1["responses"]["BadRequestError"];
+                401: components$1["responses"]["UnauthorizedError"];
+                403: components$1["responses"]["ForbiddenError"];
+                /** @description Automation not found. */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                429: components$1["responses"]["RateLimitError"];
+                500: components$1["responses"]["InternalServerError"];
+            };
+        };
         delete?: never;
         /** @description Handles preflight requests. This endpoint allows CORS. */
         options: {
@@ -315,7 +382,12 @@ interface paths {
             path?: never;
             cookie?: never;
         };
-        /** @description Lists the automations for a project. */
+        /**
+         * @deprecated
+         * @description Lists the automations for a project.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
         get: {
             parameters: {
                 query: {
@@ -407,7 +479,12 @@ interface paths {
                 500: components["responses"]["InternalServerError"];
             };
         };
-        /** @description Deploys (creates or updates) an automation. */
+        /**
+         * @deprecated
+         * @description Deploys (creates or updates) an automation.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
         put: {
             parameters: {
                 query?: never;
@@ -483,7 +560,12 @@ interface paths {
             };
         };
         post?: never;
-        /** @description Deletes an automation and its run history. */
+        /**
+         * @deprecated
+         * @description Deletes an automation and its run history.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
         delete: {
             parameters: {
                 query?: never;
@@ -543,7 +625,12 @@ interface paths {
             };
         };
         head?: never;
-        /** @description Toggles the enabled state of an automation. Disabled automations do not run when their trigger occurs. */
+        /**
+         * @deprecated
+         * @description Toggles the enabled state of an automation. Disabled automations do not run when their trigger occurs.
+         *
+         *     This is experimental functionality that is subject to change without notice.
+         */
         patch: {
             parameters: {
                 query?: never;
@@ -653,6 +740,7 @@ type AutomationsDeployInput = Omit<AutomationsDeployBody, 'projectId'>;
 type AutomationRunsListResponse = paths$1['/api/v1/automation-runs']['get']['responses']['200']['content']['application/json'];
 type AutomationRunSummary = AutomationRunsListResponse['runs'][number];
 type AutomationRunStatus = AutomationRunSummary['status'];
+type AutomationRunTriggerResponse = paths$1['/api/v1/automation-runs']['post']['responses']['202']['content']['application/json'];
 type AutomationRunLogEntry = paths$2['/api/v1/automation-run-logs']['get']['responses']['200']['content']['application/json']['logs'][number];
 
 type AutomationsClientOptions = Omit<ClientOptions, 'projectId'> & {
@@ -687,6 +775,15 @@ declare class AutomationsClient extends ApiClient<AutomationsClientOptions> {
      * @param publicId - The automation public ID.
      */
     remove(publicId: string): Promise<void>;
+    /**
+     * Triggers a one-off run of a scheduled automation, for testing. The run is identical to a real
+     * scheduled occurrence but is enqueued out of band: it does not advance the schedule and runs even
+     * when the automation is disabled. Only `schedule`-triggered automations may be run this way.
+     *
+     * @param publicId - The automation public ID.
+     * @returns The enqueued run ID; poll {@link listRuns} to observe its outcome.
+     */
+    run(publicId: string): Promise<AutomationRunTriggerResponse>;
     /**
      * Lists automation runs for the project, optionally filtered by automation and status.
      */
@@ -704,4 +801,4 @@ declare class AutomationsClient extends ApiClient<AutomationsClientOptions> {
     listRunLogs(runId: string): Promise<AutomationRunLogEntry[]>;
 }
 
-export { type AutomationRunLogEntry, type AutomationRunStatus, type AutomationRunSummary, type AutomationRunsListResponse, type AutomationSummary, type AutomationTriggerType, AutomationsClient, type AutomationsClientOptions, type AutomationsDeployBody, type AutomationsDeployInput, type AutomationsListResponse };
+export { type AutomationRunLogEntry, type AutomationRunStatus, type AutomationRunSummary, type AutomationRunTriggerResponse, type AutomationRunsListResponse, type AutomationSummary, type AutomationTriggerType, AutomationsClient, type AutomationsClientOptions, type AutomationsDeployBody, type AutomationsDeployInput, type AutomationsListResponse };

package/dist/api/index.mjs

@@ -59,6 +59,21 @@ var _AutomationsClient = class _AutomationsClient extends ApiClient {
       expectNoContent: true
     });
   }
+  /**
+   * Triggers a one-off run of a scheduled automation, for testing. The run is identical to a real
+   * scheduled occurrence but is enqueued out of band: it does not advance the schedule and runs even
+   * when the automation is disabled. Only `schedule`-triggered automations may be run this way.
+   *
+   * @param publicId - The automation public ID.
+   * @returns The enqueued run ID; poll {@link listRuns} to observe its outcome.
+   */
+  async run(publicId) {
+    const { projectId } = this.options;
+    return await this.apiClient(this.createUrl(__privateGet(_AutomationsClient, _runsUrl)), {
+      method: "POST",
+      body: JSON.stringify({ projectId, publicId })
+    });
+  }
   /**
    * Lists automation runs for the project, optionally filtered by automation and status.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniformdev/automations-sdk",
-  "version": "20.50.2-alpha.109+846837c66a",
+  "version": "20.50.2-alpha.149+913f0b7b57",
   "description": "Uniform Automations SDK",
   "license": "SEE LICENSE IN LICENSE.txt",
   "exports": {
@@ -40,8 +40,8 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@uniformdev/context": "20.50.2-alpha.109+846837c66a",
-    "@uniformdev/webhooks": "20.50.2-alpha.109+846837c66a"
+    "@uniformdev/context": "20.50.2-alpha.149+913f0b7b57",
+    "@uniformdev/webhooks": "20.50.2-alpha.149+913f0b7b57"
   },
   "peerDependencies": {
     "ai": "^6.0.0",
@@ -62,5 +62,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "846837c66ad0f518683c100615b59b27f91498ba"
+  "gitHead": "913f0b7b57295ca79575810663c56a7a5deea9e4"
 }