@useago/sdk 0.4.3 → 0.4.5

package/dist/react.d.cts

@@ -542,6 +542,19 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
  */
 export declare function createMockClient(options?: MockAgoClientOptions): MockAgoClient;
 
+/**
+ * Compute which required fields are still empty and whether the form is complete.
+ * Pure — the single home for the "required + non-empty" rule, shared by the update
+ * handler, submit, the dynamic context, and the React hook. Derived on read so the
+ * store only ever holds canonical state ({@link FormCollectorState}).
+ *
+ * Requiredness is answer-dependent: a field listed in `required` is required unless
+ * it carries a `requiredWhen` that doesn't currently hold, and any field whose
+ * `requiredWhen` holds becomes required. So conditional fields surface in `missing`
+ * exactly when the answers make them relevant.
+ */
+export declare function deriveFormStatus(schema: FormCollectorSchema, values: Partial<Record<string, unknown>>): FormCollectorStatus;
+
 /**
  * A function that returns a fresh context entry on demand.
  * Evaluated every time a message is sent — use it to pull data from stores,
@@ -577,22 +590,29 @@ export declare interface FormCollector<V = Record<string, unknown>> {
 }
 
 /**
- * JSON-schema shape of a form's fields — identical to a client function's
- * `parameters`, so one schema feeds the store, the update function, and the
- * dynamic context with no second type.
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
  */
-export declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+export declare interface FormCollectorSchema {
+    type: "object";
+    properties: Record<string, FormFieldSchema>;
+    required?: string[];
+}
 
-/** Live state held in the collector's store. */
+/** Canonical, source-of-truth state held in the collector's store. */
 export declare interface FormCollectorState<V = Record<string, unknown>> {
     /** Field values collected so far. */
     values: Partial<V>;
+    /** True once a submit succeeded. */
+    submitted: boolean;
+}
+
+/** Completeness status derived from values + schema — computed on read, never stored. */
+export declare interface FormCollectorStatus {
     /** Required field names still empty. */
     missing: string[];
     /** True when no required field is missing. */
     complete: boolean;
-    /** True once a submit succeeded. */
-    submitted: boolean;
 }
 
 declare interface FormField {
@@ -603,6 +623,43 @@ declare interface FormField {
     default?: unknown;
 }
 
+/**
+ * A field's conditional-requiredness rule. The field becomes required exactly
+ * when the controlling `property` matches `value` against the answers collected
+ * so far:
+ * - a single `value`, no `op` — equality (compared as strings);
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
+ * - an array `value`, no `op` — "one of": matches when the property equals any
+ *   listed value.
+ *
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
+ */
+declare interface FormFieldCondition {
+    /** The controlling field whose value the rule tests. */
+    property: string;
+    /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
+    op?: ">=" | "<=" | ">" | "<";
+    /**
+     * The value(s) to test the controlling field against. A single value is an
+     * equality (or, with `op`, a numeric comparison); an array is an "is one of"
+     * membership test, e.g. `value: ["1", "2", "3"]`.
+     */
+    value: string | number | Array<string | number>;
+}
+
+/** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
+declare interface FormFieldSchema {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /**
+     * Makes the field required only while this condition holds. Drives the dynamic
+     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     */
+    requiredWhen?: FormFieldCondition;
+}
+
 /**
  * Form schema for tool calls requiring user input
  */
@@ -994,8 +1051,11 @@ export declare interface UseConversationResult {
 export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): UseFormCollectorResult<V>;
 
 export declare interface UseFormCollectorResult<V = Record<string, unknown>> extends FormCollector<V> {
-    /** Live form state from the collector's store — re-renders on every change. */
-    state: FormCollectorState<V>;
+    /**
+     * Live form state from the store (`values`, `submitted`) plus the completeness
+     * status (`missing`, `complete`) derived on read — re-renders on every change.
+     */
+    state: FormCollectorState<V> & FormCollectorStatus;
 }
 
 /**

package/dist/react.d.ts

@@ -542,6 +542,19 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
  */
 export declare function createMockClient(options?: MockAgoClientOptions): MockAgoClient;
 
+/**
+ * Compute which required fields are still empty and whether the form is complete.
+ * Pure — the single home for the "required + non-empty" rule, shared by the update
+ * handler, submit, the dynamic context, and the React hook. Derived on read so the
+ * store only ever holds canonical state ({@link FormCollectorState}).
+ *
+ * Requiredness is answer-dependent: a field listed in `required` is required unless
+ * it carries a `requiredWhen` that doesn't currently hold, and any field whose
+ * `requiredWhen` holds becomes required. So conditional fields surface in `missing`
+ * exactly when the answers make them relevant.
+ */
+export declare function deriveFormStatus(schema: FormCollectorSchema, values: Partial<Record<string, unknown>>): FormCollectorStatus;
+
 /**
  * A function that returns a fresh context entry on demand.
  * Evaluated every time a message is sent — use it to pull data from stores,
@@ -577,22 +590,29 @@ export declare interface FormCollector<V = Record<string, unknown>> {
 }
 
 /**
- * JSON-schema shape of a form's fields — identical to a client function's
- * `parameters`, so one schema feeds the store, the update function, and the
- * dynamic context with no second type.
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
  */
-export declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+export declare interface FormCollectorSchema {
+    type: "object";
+    properties: Record<string, FormFieldSchema>;
+    required?: string[];
+}
 
-/** Live state held in the collector's store. */
+/** Canonical, source-of-truth state held in the collector's store. */
 export declare interface FormCollectorState<V = Record<string, unknown>> {
     /** Field values collected so far. */
     values: Partial<V>;
+    /** True once a submit succeeded. */
+    submitted: boolean;
+}
+
+/** Completeness status derived from values + schema — computed on read, never stored. */
+export declare interface FormCollectorStatus {
     /** Required field names still empty. */
     missing: string[];
     /** True when no required field is missing. */
     complete: boolean;
-    /** True once a submit succeeded. */
-    submitted: boolean;
 }
 
 declare interface FormField {
@@ -603,6 +623,43 @@ declare interface FormField {
     default?: unknown;
 }
 
+/**
+ * A field's conditional-requiredness rule. The field becomes required exactly
+ * when the controlling `property` matches `value` against the answers collected
+ * so far:
+ * - a single `value`, no `op` — equality (compared as strings);
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
+ * - an array `value`, no `op` — "one of": matches when the property equals any
+ *   listed value.
+ *
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
+ */
+declare interface FormFieldCondition {
+    /** The controlling field whose value the rule tests. */
+    property: string;
+    /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
+    op?: ">=" | "<=" | ">" | "<";
+    /**
+     * The value(s) to test the controlling field against. A single value is an
+     * equality (or, with `op`, a numeric comparison); an array is an "is one of"
+     * membership test, e.g. `value: ["1", "2", "3"]`.
+     */
+    value: string | number | Array<string | number>;
+}
+
+/** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
+declare interface FormFieldSchema {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /**
+     * Makes the field required only while this condition holds. Drives the dynamic
+     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     */
+    requiredWhen?: FormFieldCondition;
+}
+
 /**
  * Form schema for tool calls requiring user input
  */
@@ -994,8 +1051,11 @@ export declare interface UseConversationResult {
 export declare function useFormCollector<V = Record<string, unknown>>(options: CreateFormCollectorOptions<V>): UseFormCollectorResult<V>;
 
 export declare interface UseFormCollectorResult<V = Record<string, unknown>> extends FormCollector<V> {
-    /** Live form state from the collector's store — re-renders on every change. */
-    state: FormCollectorState<V>;
+    /**
+     * Live form state from the store (`values`, `submitted`) plus the completeness
+     * status (`missing`, `complete`) derived on read — re-renders on every change.
+     */
+    state: FormCollectorState<V> & FormCollectorStatus;
 }
 
 /**