@colixsystems/widget-sdk 0.288.0 → 0.290.0

package/README.md

@@ -90,7 +90,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.288.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**.
+`v0.290.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.290.0 (contract 1.238.0)
+
+**New `useConnector(connectorRef)` hook — a widget can call one of the workspace's REST connectors and use the answer itself.** Bind a connector with a `{ type: "connectorRef" }` property and declare `connectors.call:*` in `requestedScopes`. `call(operation, { params, query, body })` names an operation the workspace listed for apps on that connector — never a method or a path — and resolves `{ status, content_type, body }` with the outside API's status and parsed body. The whole call has 250 ms, token exchange included: a slower outside API is cut off and the call rejects with `UPSTREAM_TIMEOUT`. The credential is added on the server and never reaches the app. A new `connectors` host client (`createConnectorsClient` in `@colixsystems/actions-client`), the `connectorRef` property type, the `connectors.call:*` scope and a `ConnectorError`. Everything is additive.
+
+### What's new in 0.289.0 (contract 1.237.0)
+
+**`manifest.translations` may declare up to 500 keys (was 200).** A widget with many screens, or one that ships every label of a large form, no longer runs out of keys. Widening: every manifest that validated before still does.
 
 ### What's new in 0.288.0 (contract 1.236.0)
 

package/dist/contract.cjs

@@ -2299,6 +2299,46 @@ const HOOKS = [
     requiredContextSlice: ["actions.run"],
     scopes: ["actions.run:*"],
   },
+  {
+    name: "useConnector",
+    signature: "useConnector(connectorRef)",
+    description:
+      "sc-15659 — call one of the WORKSPACE's REST connectors (a configured " +
+      "outside API) straight from the widget, and use the answer in the " +
+      "widget. call(operation, { params, query, body }) names an OPERATION " +
+      "the workspace listed for apps on that connector, never a method or a " +
+      "path: the server builds the request from the listing and adds the " +
+      "connector's credential, which never reaches the app. `params` fills " +
+      "the operation's {name} path segments (one whole segment each, no " +
+      "slashes); `query` may use only the names the operation lists; `body` " +
+      "only where the operation takes one. call resolves with { status, " +
+      "content_type, body } — the outside API's status (a non-2xx answer " +
+      "still resolves: branch on status) and its parsed JSON or text body. " +
+      "The whole call must finish within 250 ms, token exchange included: a " +
+      "slower outside API is cut off and the call rejects with UPSTREAM_TIMEOUT. " +
+      "May run on mount for a read operation; an operation that changes data " +
+      "belongs in an event handler. `connectorRef` is a connector id an " +
+      "author bound through a `connectorRef` property — when it is missing, " +
+      "or the host brokers no connectors client, `available` is false and " +
+      "call() rejects UNAVAILABLE; render a visible 'pick a connector' state, " +
+      "NEVER a blank box. Only signed-in app users may call. ConnectorError.code: " +
+      "OPERATION_NOT_ALLOWED (403), CONNECTOR_NOT_FOUND (404, also when the " +
+      "connector is not callable from the app) and CONNECTOR_SETUP_INCOMPLETE " +
+      "(409) will NOT clear on a retry, so show an 'isn't available' state; " +
+      "RATE_LIMITED (429) will; INVALID_CONNECTOR_PARAMS (400) means an " +
+      "argument the operation does not take; UPSTREAM_ERROR (502) and " +
+      "UPSTREAM_TIMEOUT (504) mean the outside API failed; AUTH_REQUIRED, " +
+      "TOKEN_EXPIRED and TOKEN_INVALID mean the app user must sign in. NEVER " +
+      "show an app user a raw error. Reads ctx.connectors.",
+    returnShape: {
+      available: "boolean  // false when no connector is bound or the host brokers none",
+      call: "(operation, { params?, query?, body? }) => Promise<{ status, content_type, body }>  // rejects with ConnectorError",
+      calling: "boolean  // true while any call is in flight",
+      error: "ConnectorError | null  // the last call's error; cleared by the next call or a rebind",
+    },
+    requiredContextSlice: ["connectors.call"],
+    scopes: ["connectors.call:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -4176,7 +4216,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤200 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
+      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤500 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
     default: {},
   },
 };
@@ -4342,6 +4382,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { run: "function", status: "function" },
   },
+  connectors: {
+    description:
+      "sc-15659 — injected connectors client from @colixsystems/actions-client. " +
+      "{ call(connectorId, operation, { params, query, body }) -> Promise<{ status, content_type, body }> }. " +
+      "Backs useConnector(). Calls one operation the workspace listed on an app-callable " +
+      "connector, as the signed-in caller; the credential is added server-side. Errors carry " +
+      "the server's `code` and `status`. Absent on a host that brokers none, where " +
+      "useConnector() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { call: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6749,7 +6800,12 @@ const CONTRACT = deepFreeze({
   //    `order: { table_id, record_id }` the server marks paid on settlement,
   //    a template column may declare `paymentStatus: true`, and four new
   //    PaymentError codes.
-  version: "1.236.0",
+  // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
+  //    (was 200).
+  // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
+  //    `connectors` host client + the `connectorRef` propertySchema type + the
+  //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  version: "1.238.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2295,6 +2295,46 @@ const HOOKS = [
     requiredContextSlice: ["actions.run"],
     scopes: ["actions.run:*"],
   },
+  {
+    name: "useConnector",
+    signature: "useConnector(connectorRef)",
+    description:
+      "sc-15659 — call one of the WORKSPACE's REST connectors (a configured " +
+      "outside API) straight from the widget, and use the answer in the " +
+      "widget. call(operation, { params, query, body }) names an OPERATION " +
+      "the workspace listed for apps on that connector, never a method or a " +
+      "path: the server builds the request from the listing and adds the " +
+      "connector's credential, which never reaches the app. `params` fills " +
+      "the operation's {name} path segments (one whole segment each, no " +
+      "slashes); `query` may use only the names the operation lists; `body` " +
+      "only where the operation takes one. call resolves with { status, " +
+      "content_type, body } — the outside API's status (a non-2xx answer " +
+      "still resolves: branch on status) and its parsed JSON or text body. " +
+      "The whole call must finish within 250 ms, token exchange included: a " +
+      "slower outside API is cut off and the call rejects with UPSTREAM_TIMEOUT. " +
+      "May run on mount for a read operation; an operation that changes data " +
+      "belongs in an event handler. `connectorRef` is a connector id an " +
+      "author bound through a `connectorRef` property — when it is missing, " +
+      "or the host brokers no connectors client, `available` is false and " +
+      "call() rejects UNAVAILABLE; render a visible 'pick a connector' state, " +
+      "NEVER a blank box. Only signed-in app users may call. ConnectorError.code: " +
+      "OPERATION_NOT_ALLOWED (403), CONNECTOR_NOT_FOUND (404, also when the " +
+      "connector is not callable from the app) and CONNECTOR_SETUP_INCOMPLETE " +
+      "(409) will NOT clear on a retry, so show an 'isn't available' state; " +
+      "RATE_LIMITED (429) will; INVALID_CONNECTOR_PARAMS (400) means an " +
+      "argument the operation does not take; UPSTREAM_ERROR (502) and " +
+      "UPSTREAM_TIMEOUT (504) mean the outside API failed; AUTH_REQUIRED, " +
+      "TOKEN_EXPIRED and TOKEN_INVALID mean the app user must sign in. NEVER " +
+      "show an app user a raw error. Reads ctx.connectors.",
+    returnShape: {
+      available: "boolean  // false when no connector is bound or the host brokers none",
+      call: "(operation, { params?, query?, body? }) => Promise<{ status, content_type, body }>  // rejects with ConnectorError",
+      calling: "boolean  // true while any call is in flight",
+      error: "ConnectorError | null  // the last call's error; cleared by the next call or a rebind",
+    },
+    requiredContextSlice: ["connectors.call"],
+    scopes: ["connectors.call:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -4172,7 +4212,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤200 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
+      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤500 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
     default: {},
   },
 };
@@ -4338,6 +4378,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { run: "function", status: "function" },
   },
+  connectors: {
+    description:
+      "sc-15659 — injected connectors client from @colixsystems/actions-client. " +
+      "{ call(connectorId, operation, { params, query, body }) -> Promise<{ status, content_type, body }> }. " +
+      "Backs useConnector(). Calls one operation the workspace listed on an app-callable " +
+      "connector, as the signed-in caller; the credential is added server-side. Errors carry " +
+      "the server's `code` and `status`. Absent on a host that brokers none, where " +
+      "useConnector() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { call: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6745,7 +6796,12 @@ const CONTRACT = deepFreeze({
   //    `order: { table_id, record_id }` the server marks paid on settlement,
   //    a template column may declare `paymentStatus: true`, and four new
   //    PaymentError codes.
-  version: "1.236.0",
+  // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
+  //    (was 200).
+  // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
+  //    `connectors` host client + the `connectorRef` propertySchema type + the
+  //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  version: "1.238.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -4118,6 +4118,115 @@ export function useAction(actionRef) {
   };
 }
 
+/**
+ * sc-15659 — what useConnector() rejects with. `code` is one of:
+ *   - "UNAVAILABLE"                — no connector bound, or the host brokers no
+ *                                    connectors client (render the unbound state)
+ *   - "OPERATION_NOT_ALLOWED"      — 403 (the workspace did not list this operation)
+ *   - "INVALID_CONNECTOR_PARAMS"   — 400 (an argument the operation does not take)
+ *   - "CONNECTOR_NOT_FOUND"        — 404 (gone, or no longer callable from the app)
+ *   - "CONNECTOR_SETUP_INCOMPLETE" — 409 (the workspace has not finished its sign-in)
+ *   - "RATE_LIMITED"               — 429 (too many calls — retry shortly)
+ *   - "AUTH_REQUIRED" / "TOKEN_EXPIRED" / "TOKEN_INVALID" — 401 (no app session)
+ *   - "UPSTREAM_ERROR" / "UPSTREAM_TIMEOUT" — 502 / 504 (the outside API failed)
+ *   - "CONNECTOR_FAILED"           — no answer came
+ *
+ * The connectors client owns these codes; any other server code passes through.
+ */
+export class ConnectorError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "ConnectorError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toConnectorError(err) {
+  if (err instanceof ConnectorError) return err;
+  const code = err && typeof err.code === "string" && err.code ? err.code : "CONNECTOR_FAILED";
+  const message = (err && err.message) || "The connector call failed";
+  return new ConnectorError(code, message, { cause: err });
+}
+
+/**
+ * sc-15659 — call one of the workspace's REST connectors through an operation
+ * the workspace listed for apps. Returns `{ available, call, calling, error }`.
+ *
+ *   call(operation, { params?, query?, body? }) → Promise<{ status, content_type, body }>
+ *
+ * The widget owns what it does with the answer. A non-2xx upstream status
+ * still resolves; a platform refusal rejects with a ConnectorError. The
+ * connector's credential is added on the server and never reaches the app.
+ *
+ * `connectorRef` is the connector id an author bound through a
+ * `connectorRef` property. When it is absent, or the host brokers no
+ * connectors client, `available` is false and `call` rejects UNAVAILABLE
+ * rather than throwing at render — render a visible unbound state.
+ *
+ * Routes through the injected `@colixsystems/actions-client` at
+ * `ctx.connectors`, so the Player and the Expo export call identically.
+ */
+export function useConnector(connectorRef) {
+  const ctx = useWidgetContextOrThrow("useConnector");
+  const available =
+    Boolean(connectorRef) && Boolean(ctx.connectors) && typeof ctx.connectors.call === "function";
+
+  const clientRef = useRef(null);
+  clientRef.current = available ? ctx.connectors : null;
+  const connectorIdRef = useRef(connectorRef);
+  connectorIdRef.current = connectorRef;
+
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  // A rebind starts clean: another connector's error never shows.
+  const [outcome, setOutcome] = useState({ boundTo: connectorRef, pending: 0, error: null });
+
+  const call = useCallback(async (operation, args) => {
+    const client = clientRef.current;
+    const connectorId = connectorIdRef.current;
+    if (!client || !connectorId) {
+      throw new ConnectorError("UNAVAILABLE", "No connector is available for this host");
+    }
+    const settle = (error) => {
+      if (!mountedRef.current) return;
+      setOutcome((prior) =>
+        prior.boundTo === connectorId
+          ? { boundTo: connectorId, pending: Math.max(0, prior.pending - 1), error }
+          : prior,
+      );
+    };
+    setOutcome((prior) =>
+      prior.boundTo === connectorId
+        ? { ...prior, pending: prior.pending + 1, error: null }
+        : { boundTo: connectorId, pending: 1, error: null },
+    );
+    try {
+      const answer = await client.call(connectorId, operation, args);
+      settle(null);
+      return answer;
+    } catch (err) {
+      const e = toConnectorError(err);
+      settle(e);
+      throw e;
+    }
+  }, []);
+
+  const current = outcome.boundTo === connectorRef;
+  return {
+    available,
+    call,
+    calling: current && outcome.pending > 0,
+    error: current ? outcome.error : null,
+  };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/index.d.ts

@@ -474,7 +474,7 @@ export interface WidgetManifest {
    * under a per-widget namespace (`widget.<id>.<key>`), so `useI18n().t(key)`
    * resolves the namespaced key automatically — the author never types the
    * prefix. Non-destructive (admin edits win; absent languages are not
-   * created) and persists across uninstalls. Caps: ≤200 keys, key matches
+   * created) and persists across uninstalls. Caps: ≤500 keys, key matches
    * /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, value ≤1 KB.
    */
   translations?: Record<string, { en: string } & Record<string, string>>;
@@ -910,6 +910,10 @@ export interface WidgetContext<TProps = unknown> {
     /** sc-14224 — whether a run would reach the script; optional on older hosts. */
     status?(actionId: string): Promise<{ available: boolean; reason: string | null }>;
   };
+  /** sc-15659 — injected @colixsystems/actions-client backing useConnector(). */
+  connectors?: {
+    call(connectorId: string, operation: string, args?: ConnectorCallArgs): Promise<ConnectorCallResult>;
+  };
   /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
   linkPreviews?: { get(url: string): Promise<LinkPreview> };
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
@@ -2105,6 +2109,40 @@ export interface ActionApi {
  */
 export function useAction(actionRef: string | null | undefined): ActionApi;
 
+export interface ConnectorCallArgs {
+  /** Values for the operation's `{name}` path segments; one whole segment each. */
+  params?: Record<string, string | number>;
+  /** Only the query names the operation lists. */
+  query?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+  /** A JSON body, only for an operation that takes one. */
+  body?: unknown;
+}
+
+/** The outside API's answer: its status (non-2xx still resolves) and parsed body. */
+export interface ConnectorCallResult {
+  status: number;
+  content_type: string | null;
+  body: unknown;
+}
+
+export interface ConnectorApi {
+  /** False when no connector is bound or the host brokers no connectors client. */
+  available: boolean;
+  /** Call one operation the workspace listed; rejects with ConnectorError. */
+  call(operation: string, args?: ConnectorCallArgs): Promise<ConnectorCallResult>;
+  /** True while any call is in flight. */
+  calling: boolean;
+  /** The last call's error; cleared by the next call or a rebind. */
+  error: ConnectorError | null;
+}
+
+/**
+ * sc-15659 — call one of the workspace's REST connectors through an operation
+ * the workspace listed for apps. The widget needs `connectors.call:*` in
+ * `requestedScopes`; the credential never reaches the app.
+ */
+export function useConnector(connectorRef: string | null | undefined): ConnectorApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"
@@ -3441,6 +3479,30 @@ export class AgentError extends Error {
  * `RATE_LIMITED` will. `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID`
  * mean the app user must sign in. Never show an app user the raw message.
  */
+/**
+ * sc-15659 — structured error thrown by `useConnector().call`. Branch on
+ * `code`: `OPERATION_NOT_ALLOWED`, `CONNECTOR_NOT_FOUND` and
+ * `CONNECTOR_SETUP_INCOMPLETE` will not clear on a retry, `RATE_LIMITED` will.
+ * Never show an app user the raw message.
+ */
+export class ConnectorError extends Error {
+  code:
+    | "UNAVAILABLE"
+    | "INVALID_CONNECTOR_PARAMS"
+    | "OPERATION_NOT_ALLOWED"
+    | "CONNECTOR_NOT_FOUND"
+    | "CONNECTOR_SETUP_INCOMPLETE"
+    | "RATE_LIMITED"
+    | "AUTH_REQUIRED"
+    | "TOKEN_EXPIRED"
+    | "TOKEN_INVALID"
+    | "UPSTREAM_ERROR"
+    | "UPSTREAM_TIMEOUT"
+    | "CONNECTOR_FAILED"
+    | (string & {});
+  constructor(code: string, message: string, opts?: { cause?: unknown });
+}
+
 export class ActionError extends Error {
   code:
     | "UNAVAILABLE"

package/dist/index.js

@@ -30,6 +30,7 @@ export {
   PermissionError,
   AgentError,
   ActionError,
+  ConnectorError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -39,6 +40,7 @@ export {
   useInterpretDraft,
   useAgent,
   useAction,
+  useConnector,
   useAsset,
   useAssetsByTag,
   useBundledAsset,

package/dist/index.native.js

@@ -30,6 +30,7 @@ export {
   PermissionError,
   AgentError,
   ActionError,
+  ConnectorError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -39,6 +40,7 @@ export {
   useInterpretDraft,
   useAgent,
   useAction,
+  useConnector,
   useAsset,
   useAssetsByTag,
   useBundledAsset,

package/dist/linter.cjs

@@ -861,6 +861,16 @@ function _scopeRules(source, manifest) {
       snippet: "",
     });
   }
+  // sc-15659 — DISCLOSURE, as for useAction: the server gate is the app-user
+  // JWT plus the connector's app opt-in and listed operations.
+  if (/\buseConnector\s*\(/.test(source) && !declared.has("connectors.call:*")) {
+    findings.push({
+      rule: "scope-required-for-useConnector",
+      label: "useConnector() requires `connectors.call:*` in manifest.requestedScopes",
+      line: 0,
+      snippet: "",
+    });
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/linter.js

@@ -856,6 +856,16 @@ function _scopeRules(source, manifest) {
       snippet: "",
     });
   }
+  // sc-15659 — DISCLOSURE, as for useAction: the server gate is the app-user
+  // JWT plus the connector's app opt-in and listed operations.
+  if (/\buseConnector\s*\(/.test(source) && !declared.has("connectors.call:*")) {
+    findings.push({
+      rule: "scope-required-for-useConnector",
+      label: "useConnector() requires `connectors.call:*` in manifest.requestedScopes",
+      line: 0,
+      snippet: "",
+    });
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;

package/dist/manifest.cjs

@@ -47,8 +47,8 @@ const VALID_PLATFORMS = new Set(["web", "native"]);
 // backend/src/core/services/l10n.service.js). The locale pattern mirrors that
 // service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
 // would reject.
-// One page of the dictionary's widget namespace (l10n MAX_KEYS_PER_PAGE).
-const TRANSLATIONS_MAX_KEYS = 200;
+// Bounds one package's rows in a workspace's translation dictionary.
+const TRANSLATIONS_MAX_KEYS = 500;
 const TRANSLATION_VALUE_MAX_BYTES = 1024;
 const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
 const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;

package/dist/manifest.js

@@ -42,8 +42,8 @@ const VALID_PLATFORMS = new Set(["web", "native"]);
 // backend/src/core/services/l10n.service.js). The locale pattern mirrors that
 // service's LANG_CODE_RE so a manifest can't declare a locale the dictionary
 // would reject.
-// One page of the dictionary's widget namespace (l10n MAX_KEYS_PER_PAGE).
-const TRANSLATIONS_MAX_KEYS = 200;
+// Bounds one package's rows in a workspace's translation dictionary.
+const TRANSLATIONS_MAX_KEYS = 500;
 const TRANSLATION_VALUE_MAX_BYTES = 1024;
 const TRANSLATION_KEY_RE = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
 const TRANSLATION_LOCALE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;

package/dist/property-schema.js

@@ -32,6 +32,9 @@ const VALID_TYPES = new Set([
   // sc-13843: `actionRef` picks one of the workspace's Actions, a bare
   // Action UUID a widget passes to `useAction(actionRef)`. Remapped like agentRef.
   "actionRef",
+  // sc-15659: `connectorRef` picks one of the workspace's app-callable REST
+  // connectors, a bare id a widget passes to `useConnector`. Remapped likewise.
+  "connectorRef",
   // REQ-WDG-PAGEREF: `pageRef` is a page picker that emits a bare AppPage
   // UUID into the page JSON. Renders a page `<select>` in the Studio
   // Properties Panel; a widget reads it and navigates via
@@ -164,6 +167,7 @@ function coerceLeaf(def, value, path, errors) {
     case "sectionRef":
     case "agentRef":
     case "actionRef":
+    case "connectorRef":
     case "richText":
     case "asset":
     case "folderRef":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.288.0",
+  "version": "0.290.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -2295,6 +2295,46 @@ const HOOKS = [
     requiredContextSlice: ["actions.run"],
     scopes: ["actions.run:*"],
   },
+  {
+    name: "useConnector",
+    signature: "useConnector(connectorRef)",
+    description:
+      "sc-15659 — call one of the WORKSPACE's REST connectors (a configured " +
+      "outside API) straight from the widget, and use the answer in the " +
+      "widget. call(operation, { params, query, body }) names an OPERATION " +
+      "the workspace listed for apps on that connector, never a method or a " +
+      "path: the server builds the request from the listing and adds the " +
+      "connector's credential, which never reaches the app. `params` fills " +
+      "the operation's {name} path segments (one whole segment each, no " +
+      "slashes); `query` may use only the names the operation lists; `body` " +
+      "only where the operation takes one. call resolves with { status, " +
+      "content_type, body } — the outside API's status (a non-2xx answer " +
+      "still resolves: branch on status) and its parsed JSON or text body. " +
+      "The whole call must finish within 250 ms, token exchange included: a " +
+      "slower outside API is cut off and the call rejects with UPSTREAM_TIMEOUT. " +
+      "May run on mount for a read operation; an operation that changes data " +
+      "belongs in an event handler. `connectorRef` is a connector id an " +
+      "author bound through a `connectorRef` property — when it is missing, " +
+      "or the host brokers no connectors client, `available` is false and " +
+      "call() rejects UNAVAILABLE; render a visible 'pick a connector' state, " +
+      "NEVER a blank box. Only signed-in app users may call. ConnectorError.code: " +
+      "OPERATION_NOT_ALLOWED (403), CONNECTOR_NOT_FOUND (404, also when the " +
+      "connector is not callable from the app) and CONNECTOR_SETUP_INCOMPLETE " +
+      "(409) will NOT clear on a retry, so show an 'isn't available' state; " +
+      "RATE_LIMITED (429) will; INVALID_CONNECTOR_PARAMS (400) means an " +
+      "argument the operation does not take; UPSTREAM_ERROR (502) and " +
+      "UPSTREAM_TIMEOUT (504) mean the outside API failed; AUTH_REQUIRED, " +
+      "TOKEN_EXPIRED and TOKEN_INVALID mean the app user must sign in. NEVER " +
+      "show an app user a raw error. Reads ctx.connectors.",
+    returnShape: {
+      available: "boolean  // false when no connector is bound or the host brokers none",
+      call: "(operation, { params?, query?, body? }) => Promise<{ status, content_type, body }>  // rejects with ConnectorError",
+      calling: "boolean  // true while any call is in flight",
+      error: "ConnectorError | null  // the last call's error; cleared by the next call or a rebind",
+    },
+    requiredContextSlice: ["connectors.call"],
+    scopes: ["connectors.call:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -4172,7 +4212,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤200 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
+      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤500 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
     default: {},
   },
 };
@@ -4338,6 +4378,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { run: "function", status: "function" },
   },
+  connectors: {
+    description:
+      "sc-15659 — injected connectors client from @colixsystems/actions-client. " +
+      "{ call(connectorId, operation, { params, query, body }) -> Promise<{ status, content_type, body }> }. " +
+      "Backs useConnector(). Calls one operation the workspace listed on an app-callable " +
+      "connector, as the signed-in caller; the credential is added server-side. Errors carry " +
+      "the server's `code` and `status`. Absent on a host that brokers none, where " +
+      "useConnector() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { call: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6745,7 +6796,12 @@ const CONTRACT = deepFreeze({
   //    `order: { table_id, record_id }` the server marks paid on settlement,
   //    a template column may declare `paymentStatus: true`, and four new
   //    PaymentError codes.
-  version: "1.236.0",
+  // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
+  //    (was 200).
+  // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
+  //    `connectors` host client + the `connectorRef` propertySchema type + the
+  //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  version: "1.238.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,