@mochabug/adapt-sdk 0.4.1 → 0.4.3

package/dist/openai/index.d.ts

@@ -70,7 +70,34 @@ export interface ConvertFailure {
  * Check `success` first, then narrow on `kind` (`'json'` or `'binary'`)
  * for successful results.
  */
-export type ConvertResult = ConvertSuccessJson | ConvertSuccessBinary | ConvertFailure;
+/**
+ * Successful conversion result for multiple signal descriptors.
+ *
+ * Returned when the conversion was created via {@link OpenAIConversion.fromSignals}.
+ * Contains per-signal results keyed by signal name.
+ */
+export interface ConvertSuccessSignals {
+    success: true;
+    kind: 'signals';
+    /**
+     * Per-signal values in dispatch-ready format.
+     *
+     * JSON signals are raw values (the JTD-validated data).
+     * Binary signals are `{ data: Uint8Array, mimeType: string, filename?: string }`.
+     *
+     * This record can be passed directly to `dispatchExchange()` or `send()`.
+     */
+    signals: Record<string, unknown>;
+}
+/** Union of all successful conversion outcomes. */
+export type ConvertSuccess = ConvertSuccessJson | ConvertSuccessBinary | ConvertSuccessSignals;
+/**
+ * Discriminated union of conversion outcomes.
+ *
+ * Check `success` first, then narrow on `kind` (`'json'`, `'binary'`, or
+ * `'signals'`) for successful results.
+ */
+export type ConvertResult = ConvertSuccess | ConvertFailure;
 /**
  * Converts JTD schemas or Adapt signal descriptors into OpenAI-compatible
  * JSON Schema (strict mode), and converts raw LLM output back into
@@ -123,7 +150,7 @@ export type ConvertResult = ConvertSuccessJson | ConvertSuccessBinary | ConvertF
  * const restored = OpenAIConversion.fromJSON(cached);
  * ```
  */
-export declare class OpenAIConversion {
+export declare class OpenAIConversion<T extends ConvertSuccess = ConvertSuccess> {
     /** The OpenAI-specific JSON Schema to pass to the OpenAI API as the response format. */
     readonly schema: OpenAISchema;
     /**
@@ -145,6 +172,11 @@ export declare class OpenAIConversion {
      * Set when created via {@link fromSignal}; `undefined` when created via {@link fromJTD}.
      */
     readonly descriptor?: SignalDescriptorJson;
+    /**
+     * The original signal descriptors used to build this conversion.
+     * Set when created via {@link fromSignals}; `undefined` otherwise.
+     */
+    readonly descriptors?: SignalDescriptorJson[];
     /**
      * Build a conversion from a JTD schema.
      *
@@ -160,7 +192,7 @@ export declare class OpenAIConversion {
      * @throws If the schema contains an unknown JTD type, an unresolved `ref`,
      *         or nesting exceeding 32 levels.
      */
-    static fromJTD(jtdSchema: JTDSchemaJson): OpenAIConversion;
+    static fromJTD(jtdSchema: JTDSchemaJson): OpenAIConversion<ConvertSuccessJson>;
     /**
      * Build a conversion from an Adapt signal descriptor.
      *
@@ -175,18 +207,48 @@ export declare class OpenAIConversion {
      * @throws If the descriptor has no formats, or a format has neither
      *         `jtdSchema` nor `mimeType`.
      */
-    static fromSignal(descriptor: SignalDescriptorJson): OpenAIConversion;
+    static fromSignal(descriptor: SignalDescriptorJson): OpenAIConversion<ConvertSuccessJson | ConvertSuccessBinary>;
+    /**
+     * Build a conversion from multiple signal descriptors.
+     *
+     * Produces an object schema with one property per signal, suitable for
+     * use as structured output parameters. Each signal's schema is built via
+     * {@link fromSignal} internally.
+     *
+     * For OpenAI strict mode, optional signals are made nullable and all
+     * properties are added to `required`.
+     *
+     * If there is only one signal with a single format, the schema is
+     * unwrapped to avoid unnecessary nesting — the signal's format schema
+     * is used directly as the object property value.
+     *
+     * Receiver/transceiver compatible:
+     * ```ts
+     * const conv = OpenAIConversion.fromSignals(
+     *   receiver.signals!,
+     *   receiver.description,
+     *   receiver.name
+     * );
+     * ```
+     *
+     * @param signals - Array of signal descriptors.
+     * @param description - Optional description for the compound schema.
+     * @param label - Optional label (not used by OpenAI, reserved for other providers).
+     * @returns A new {@link OpenAIConversion} with `descriptors` set.
+     * @throws If any signal has no formats or an invalid format.
+     */
+    static fromSignals(signals: SignalDescriptorJson[], description?: string, label?: string): OpenAIConversion<ConvertSuccessSignals>;
     /**
      * Restore an {@link OpenAIConversion} from its serialized form.
      *
      * Accepts either the JSON string produced by `JSON.stringify(conv)` or the
-     * already-parsed plain object. The original `jtdSchema` or `descriptor` is
-     * re-processed through the corresponding factory, so the restored instance
-     * is fully functional.
+     * already-parsed plain object. The original `jtdSchema`, `descriptor`, or
+     * `descriptors` is re-processed through the corresponding factory, so the
+     * restored instance is fully functional.
      *
      * @param data - A JSON string or parsed object previously produced by {@link toJSON}.
      * @returns A fully reconstructed {@link OpenAIConversion}.
-     * @throws If the serialized data contains neither `jtdSchema` nor `descriptor`.
+     * @throws If the serialized data contains neither `jtdSchema`, `descriptor`, nor `descriptors`.
      */
     static fromJSON(data: string | Record<string, unknown>): OpenAIConversion;
     private constructor();
@@ -213,7 +275,7 @@ export declare class OpenAIConversion {
      * @param json - The raw value returned by the OpenAI API (typically parsed JSON).
      * @returns A {@link ConvertResult} indicating success or failure with errors.
      */
-    convert: (json: unknown) => ConvertResult;
+    convert: (json: unknown) => T | ConvertFailure;
     /**
      * Produce a JSON-serializable representation of this conversion.
      *
@@ -224,17 +286,7 @@ export declare class OpenAIConversion {
      *
      * Called automatically by `JSON.stringify(conv)`.
      */
-    toJSON(): {
-        schema: OpenAISchema;
-        strict: boolean;
-        descriptor: SignalDescriptorJson;
-        jtdSchema?: undefined;
-    } | {
-        schema: OpenAISchema;
-        strict: boolean;
-        jtdSchema: JTDSchemaJson | undefined;
-        descriptor?: undefined;
-    };
+    toJSON(): Record<string, unknown>;
 }
 /**
  * Convenience alias for {@link OpenAIConversion.fromJTD}.

package/dist/openai/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openai/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,QAAQ,CAAC;AAOhB;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,KAAK,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,oBAAoB,GACpB,cAAc,CAAC;AA6iBnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAI3C;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,gBAAgB;IAyB1D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,oBAAoB,GAAG,gBAAgB;IAKrE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAezE,OAAO;IAcP;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,GAAI,MAAM,OAAO,KAAG,aAAa,CAQtC;IAIF;;;;;;;;;OASG;IACH,MAAM;;;;;;;;;;;CAcP;AAwLD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,GACvB,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,gBAAgB,CAElB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openai/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EAErB,MAAM,QAAQ,CAAC;AAOhB;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,KAAK,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,mDAAmD;AACnD,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,oBAAoB,GACpB,qBAAqB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,cAAc,CAAC;AA0jB5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;IACrE,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAI9C;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CACZ,SAAS,EAAE,aAAa,GACvB,gBAAgB,CAAC,kBAAkB,CAAC;IAyBvC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,UAAU,CACf,UAAU,EAAE,oBAAoB,GAC/B,gBAAgB,CAAC,kBAAkB,GAAG,oBAAoB,CAAC;IAK9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,WAAW,CAChB,OAAO,EAAE,oBAAoB,EAAE,EAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,gBAAgB,CAAC,qBAAqB,CAAC;IA2C1C;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB;IAwBzE,OAAO;IAgBP;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,GAAI,MAAM,OAAO,KAAG,CAAC,GAAG,cAAc,CAY3C;IAIF;;;;;;;;;OASG;IACH,MAAM;CAuBP;AAyPD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,GACvB,gBAAgB,CAElB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,oBAAoB,GAC/B,gBAAgB,CAElB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mochabug/adapt-sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "The API toolkit to facilitate mochabug adapt plugin development",
   "publishConfig": {
     "access": "public"