@colixsystems/widget-sdk 0.91.0 → 0.92.0

package/README.md

@@ -41,6 +41,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
+| **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
@@ -64,6 +65,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.91.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.92.0 (contract 1.65.0)
+
+**New `useInterpretDraft(tableId)` hook — turn one sentence into DRAFT record values.** A new DATASTORE hook reading a new `interpret` method on the existing `ctx.datastore` slice (`@colixsystems/datastore-client` 0.13.0). Returns `{ interpret, interpreting, error, result, available }`. Call `interpret(text, { fields, timeZone })` **imperatively** from an event handler — never on mount or in a render loop — and it resolves to `{ values, unresolved }`, where `values` is keyed by column NAME (the same shape `useDatastoreMutation().create` takes) and `unresolved` names the fields the sentence did not state.
+
+**It DRAFTS and writes nothing.** Prefill your inputs from `values`, let the person review and correct them, then submit as usual. A model reading free text must never create a record on its own.
+
+Only columns a sentence can honestly produce are drafted — string, text, number, float, boolean, date, datetime and array. `FILE`, `RELATION`, `USER` and `USER_GROUP` are never guessed because they carry identifiers, and encrypted columns are skipped. Every value is coerced against its column's `data_type` and dropped when it does not fit, so a value the model got wrong is reported `unresolved` rather than written through.
+
+**Every call spends the workspace's AI credits** and is rate-limited per actor. Once the workspace runs out, the call is refused with a **generic** 429: the person filling the form is never told the workspace's billing state — they have not heard of an AI credit and cannot buy one. Never surface a raw error to them; say drafting is unavailable and keep every field editable by hand. `available` is `false` where the host brokers no interpreter (an unbound preview, or an export with no reachable backend) — hide the affordance rather than rendering a dead button.
+
+Additive — one new hook, one new client method, one new context-slice function; no existing export changed signature.
+
 ### What's new in 0.91.0 (contract 1.64.0)
 
 **New `useSpeechToText()` hook — dictate into text with the device's on-device recogniser.** A new CORE hook reading a new `speech` capability on the existing `ctx.device` slice. Returns `{ transcript, partial, listening, supported, error, start, stop, abort, reset }`. Capture is **imperative** — call `start()` from a user gesture (a `Pressable.onPress`); the browser and the mobile OS gate the microphone prompt on a gesture, so it NEVER listens on mount. `transcript` accumulates finalised speech across utterances; `partial` holds the guess the recogniser has not committed yet (empty unless `options.interimResults`). `stop()` finalises and keeps what was heard, `abort()` discards the current utterance, `reset()` clears both. `options` (`{ lang, continuous, interimResults }`) pass through to the host. Rejections surface as a structured `SpeechToTextError` (new named export) with a stable `.code` (`PERMISSION_DENIED` / `NO_SPEECH` / `LANGUAGE_UNSUPPORTED` / `NETWORK` / `ABORTED` / `UNSUPPORTED` / `INTERNAL`). It needs **no manifest scope** and **no `requestedScopes` entry**.

package/dist/contract.cjs

@@ -820,6 +820,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.schema"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useInterpretDraft",
+    signature: "useInterpretDraft(tableId)",
+    description:
+      "sc-4932 — turns ONE sentence a user typed into DRAFT values for the " +
+      "table's columns (\"walk at 11 am tomorrow\" -> { title: 'Walk', " +
+      "due_at: '...T11:00' }). IMPERATIVE: call interpret(text, { fields, " +
+      "timeZone }) from an event handler (a button press), never on mount. It " +
+      "DRAFTS and writes NOTHING — prefill your form from `values`, let the " +
+      "user review and correct it, then submit through " +
+      "useDatastoreMutation().create as usual. `values` is keyed by column " +
+      "NAME, the same shape create() takes. `unresolved` lists the fields the " +
+      "sentence did not state — leave those blank rather than guessing. Pass " +
+      "`fields` to narrow the draft to the columns you actually render, each " +
+      "optionally carrying a dropdown's closed `options` list; pass `timeZone` " +
+      "(an IANA zone) so relative times resolve correctly. Only text, number, " +
+      "boolean, date/datetime and array columns are drafted — FILE, RELATION, " +
+      "USER and USER_GROUP columns are never guessed because they carry ids. " +
+      "Every call spends the workspace's AI CREDITS and is rate-limited per " +
+      "actor, so call it once per user action — never on mount or in a render " +
+      "loop. Once the workspace runs out of credits the call is refused with a " +
+      "generic 429 (an app user is never told the workspace's billing state — " +
+      "they have not heard of an AI credit and cannot buy one). NEVER surface a " +
+      "raw error to the person filling the form: say drafting is unavailable and " +
+      "keep every field editable by hand. Reads ctx.datastore.interpret.",
+    returnShape: {
+      interpret:
+        "(text, { fields?, timeZone? }) => Promise<{ values, unresolved }>",
+      interpreting: "boolean",
+      error: "DatastoreError | null",
+      result: "{ values, unresolved } | null",
+      available: "boolean  // false when the host brokers no interpreter",
+    },
+    requiredContextSlice: ["datastore.interpret"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -1637,13 +1673,13 @@ const WIDGET_CONTEXT_SHAPE = {
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
-      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "{ tables: { list(), get(idOrName), interpret(idOrName, body) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
       "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
       "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
-      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing). " +
       "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function", tables: "object" },
+    fields: { records: "function", schema: "function", tables: "object", interpret: "function" },
   },
   directory: {
     description:
@@ -2855,7 +2891,7 @@ const CONTRACT = deepFreeze({
   //    published widget keeps validating. The script's `triggerType` global
   //    now names the trigger that actually FIRED the run ('manual' and 'app'
   //    included), which is what makes a multi-trigger script able to branch.
-  version: "1.64.0",
+  version: "1.65.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -820,6 +820,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.schema"],
     scopes: ["datastore.read:<table>"],
   },
+  {
+    name: "useInterpretDraft",
+    signature: "useInterpretDraft(tableId)",
+    description:
+      "sc-4932 — turns ONE sentence a user typed into DRAFT values for the " +
+      "table's columns (\"walk at 11 am tomorrow\" -> { title: 'Walk', " +
+      "due_at: '...T11:00' }). IMPERATIVE: call interpret(text, { fields, " +
+      "timeZone }) from an event handler (a button press), never on mount. It " +
+      "DRAFTS and writes NOTHING — prefill your form from `values`, let the " +
+      "user review and correct it, then submit through " +
+      "useDatastoreMutation().create as usual. `values` is keyed by column " +
+      "NAME, the same shape create() takes. `unresolved` lists the fields the " +
+      "sentence did not state — leave those blank rather than guessing. Pass " +
+      "`fields` to narrow the draft to the columns you actually render, each " +
+      "optionally carrying a dropdown's closed `options` list; pass `timeZone` " +
+      "(an IANA zone) so relative times resolve correctly. Only text, number, " +
+      "boolean, date/datetime and array columns are drafted — FILE, RELATION, " +
+      "USER and USER_GROUP columns are never guessed because they carry ids. " +
+      "Every call spends the workspace's AI CREDITS and is rate-limited per " +
+      "actor, so call it once per user action — never on mount or in a render " +
+      "loop. Once the workspace runs out of credits the call is refused with a " +
+      "generic 429 (an app user is never told the workspace's billing state — " +
+      "they have not heard of an AI credit and cannot buy one). NEVER surface a " +
+      "raw error to the person filling the form: say drafting is unavailable and " +
+      "keep every field editable by hand. Reads ctx.datastore.interpret.",
+    returnShape: {
+      interpret:
+        "(text, { fields?, timeZone? }) => Promise<{ values, unresolved }>",
+      interpreting: "boolean",
+      error: "DatastoreError | null",
+      result: "{ values, unresolved } | null",
+      available: "boolean  // false when the host brokers no interpreter",
+    },
+    requiredContextSlice: ["datastore.interpret"],
+    scopes: ["datastore.read:<table>"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -1637,13 +1673,13 @@ const WIDGET_CONTEXT_SHAPE = {
   datastore: {
     description:
       "Injected @colixsystems/datastore-client instance. " +
-      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "{ tables: { list(), get(idOrName), interpret(idOrName, body) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
       "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
       "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
-      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(); `interpret` backs useInterpretDraft() (sc-4932 — drafts column values from one sentence; writes nothing). " +
       "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function", tables: "object" },
+    fields: { records: "function", schema: "function", tables: "object", interpret: "function" },
   },
   directory: {
     description:
@@ -2855,7 +2891,7 @@ const CONTRACT = deepFreeze({
   //    published widget keeps validating. The script's `triggerType` global
   //    now names the trigger that actually FIRED the run ('manual' and 'app'
   //    included), which is what makes a multi-trigger script able to branch.
-  version: "1.64.0",
+  version: "1.65.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1611,6 +1611,83 @@ export function useDatastoreSchema(tableId) {
   return { schema, loading, error, refetch };
 }
 
+/**
+ * sc-4932 — draft record values for `tableId` from one sentence the user typed.
+ * Returns `{ interpret, interpreting, error, result, available }`.
+ *
+ *   interpret(text, { fields?, timeZone? }) → Promise<{ values, unresolved }>
+ *     `values` is keyed by column NAME — the same shape
+ *     `useDatastoreMutation().create` takes — so a caller prefills its form
+ *     from it and submits through the ordinary create path. `unresolved` names
+ *     the fields the sentence did not state; they are left for the user.
+ *
+ * The hook is IMPERATIVE — it NEVER fires on mount; the widget calls
+ * `interpret` from an event handler. `interpreting` tracks an in-flight call
+ * and `error` holds the last DatastoreError (cleared at the start of each
+ * call). `result` holds the last successful draft.
+ *
+ * This DRAFTS, it does not write: the user reviews every value before the
+ * record is created. `fields` narrows the draft to the columns the caller
+ * actually renders, each optionally carrying the closed `options` list of a
+ * dropdown. `timeZone` is an IANA zone; the server resolves "at 11 am" against
+ * it and falls back to UTC when it is absent or unknown.
+ *
+ * Routes through the injected `@colixsystems/datastore-client` at
+ * `ctx.datastore.interpret`, so the Player and the Expo export resolve against
+ * the identical client. A host that brokers no interpreter (an unbound canvas
+ * preview) reports `available: false` rather than throwing, matching how
+ * useTranslate degrades.
+ */
+export function useInterpretDraft(tableId) {
+  const ctx = useWidgetContextOrThrow("useInterpretDraft");
+  const available =
+    Boolean(ctx.datastore) && typeof ctx.datastore.interpret === "function";
+
+  const fnRef = useRef(available ? ctx.datastore.interpret : null);
+  fnRef.current = available ? ctx.datastore.interpret : null;
+  const tableIdRef = useRef(tableId);
+  tableIdRef.current = tableId;
+
+  const [interpreting, setInterpreting] = useState(false);
+  const [error, setError] = useState(null);
+  const [result, setResult] = useState(null);
+
+  const interpret = useCallback(async (text, options) => {
+    const table = tableIdRef.current;
+    if (!fnRef.current || !table) {
+      throw new DatastoreError(
+        "UNAVAILABLE",
+        "No interpreter available for this host",
+      );
+    }
+    setInterpreting(true);
+    setError(null);
+    try {
+      // snake_case verbatim on the wire (REQ-GEN-09) — the SDK does not
+      // transform, so the camelCase `timeZone` argument is mapped here, once.
+      const body = { text };
+      if (options && Array.isArray(options.fields)) body.fields = options.fields;
+      if (options && options.timeZone) body.time_zone = options.timeZone;
+      const draft = await fnRef.current(table, body);
+      const safe = {
+        values: draft && draft.values ? draft.values : {},
+        unresolved:
+          draft && Array.isArray(draft.unresolved) ? draft.unresolved : [],
+      };
+      setResult(safe);
+      setInterpreting(false);
+      return safe;
+    } catch (err) {
+      const e = toDatastoreError(err);
+      setError(e);
+      setInterpreting(false);
+      throw e;
+    }
+  }, []);
+
+  return { interpret, interpreting, error, result, available };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/index.d.ts

@@ -963,6 +963,50 @@ export function useDatastoreSchema(
   tableId: string | null | undefined,
 ): SchemaResult;
 
+/** sc-4932 — one field a draft may target, with a dropdown's closed option set. */
+export interface InterpretDraftField {
+  column: string;
+  options?: Array<string | number>;
+}
+
+/** sc-4932 — options for `useInterpretDraft().interpret`. */
+export interface InterpretDraftOptions {
+  fields?: Array<InterpretDraftField | string>;
+  /** IANA zone the server resolves relative times against. Defaults to UTC. */
+  timeZone?: string;
+}
+
+/**
+ * sc-4932 — a drafted record. `values` is keyed by column NAME (the shape
+ * `useDatastoreMutation().create` takes); `unresolved` names the fields the
+ * sentence did not state.
+ */
+export interface InterpretDraftResult {
+  values: Record<string, unknown>;
+  unresolved: string[];
+}
+
+export interface InterpretDraftApi {
+  interpret(
+    text: string,
+    options?: InterpretDraftOptions,
+  ): Promise<InterpretDraftResult>;
+  interpreting: boolean;
+  error: DatastoreError | null;
+  result: InterpretDraftResult | null;
+  /** False when the host brokers no interpreter (e.g. an unbound preview). */
+  available: boolean;
+}
+
+/**
+ * sc-4932 — draft record values for `tableId` from one sentence the user typed
+ * ("walk at 11 am tomorrow"). IMPERATIVE: never fires on mount, and DRAFTS
+ * only — the user reviews the values before the record is created.
+ */
+export function useInterpretDraft(
+  tableId: string | null | undefined,
+): InterpretDraftApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"

package/dist/index.js

@@ -15,6 +15,7 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useInterpretDraft,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,

package/dist/index.native.js

@@ -15,6 +15,7 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
+  useInterpretDraft,
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.91.0",
+  "version": "0.92.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",