@lessly/sdk-app 63.3.0 → 63.4.0

package/README.md

@@ -45,6 +45,38 @@ function, so they survive destructuring (`const { list } = sdk.organization.conn
 `src/gen/manifest.gen.ts` additionally exports `operations`, the whole tool-name -> level table,
 for callers that need a level without holding a client.
 
+### Composer steps: `compositions`
+
+A catalog tool may declare a **composition** — the contract a workflow builder needs to offer that
+operation as a **step**. `src/gen/manifest.gen.ts` exports the whole table, re-exported from the
+package root:
+
+```ts
+import { compositions } from '@lessly/sdk-app';
+
+if ('mail_domain_create' in compositions) {
+  const step = compositions['mail_domain_create'];
+  step.label;            // 'Add a domain' — how a builder names the step
+  step.completion_event; // 'mail.domain.added' — the event that settles an async step
+  step.options;          // Record<string, string> — builder-level knobs
+  step.pii;              // input fields carrying personal data
+  step.secrets;          // input fields carrying secrets
+}
+```
+
+**Presence is the whole signal.** A key is in the map exactly when the catalog gave that tool a
+composition, and the value may legitimately be `{}` ("composable, nothing further to say"). Ask
+`name in compositions`; a truthiness test on `label` would drop a perfectly composable step.
+
+Every member is optional and the SDK reads none of them — the object is carried **verbatim** from
+the catalog into the generated map, so a key the platform adds reaches your App even before this
+SDK's `ToolComposition` type names it. Unlike `operations`, the map is **not** restricted to REST
+tools: composability is a property of the operation, not of its transport, so a ws-bound step is
+listed too.
+
+A tool gaining, losing or re-declaring a composition ships as a **minor** — the map only ever gains
+or loses a key, and no exported symbol appears or disappears with it.
+
 Streaming (`<tool>Connect`) factories carry neither field: a socket is neither a read nor a write,
 and the catalog declares no level for a ws-only tool.
 

package/dist/_types/gen/manifest.gen.d.ts

@@ -1,3 +1,4 @@
-import type { ToolLevel } from '../runtime/types.js';
+import type { ToolLevel, ToolComposition } from '../runtime/types.js';
 export declare const namespaces: readonly ["analytics", "brain", "consent", "content", "deployment", "mail", "observe", "organization", "playground", "realtime", "support", "tracking", "users", "waitlist", "workflow"];
 export declare const operations: Record<string, ToolLevel>;
+export declare const compositions: Record<string, ToolComposition>;

package/dist/_types/index.d.ts

@@ -4,7 +4,8 @@ export { connectStream } from './runtime/connectStream.js';
 export { LesslyApiError, isAccessDenied } from './runtime/errors.js';
 export { accessReason } from './runtime/access-reason.js';
 export { operations } from './runtime/operations.js';
-export type { LesslyAppOptions, HttpMethod, Binding, BindingsMap, ParamSpec, ParamIn, ToolLevel, Operation, } from './runtime/types.js';
+export { compositions } from './runtime/compositions.js';
+export type { LesslyAppOptions, HttpMethod, Binding, BindingsMap, ParamSpec, ParamIn, ToolLevel, ToolComposition, Operation, } from './runtime/types.js';
 export type { WsBinding, WsBindingsMap, LesslyStream, LesslyStreamOpener, StreamCloseInfo, StreamData, WebSocketCtor, WebSocketLike, } from './runtime/types.js';
 export type { Access, AccessState, AccessApi } from './runtime/access.js';
 export type { GeneratedClient } from './gen/client.gen.js';

package/dist/_types/runtime/compositions.d.ts

@@ -0,0 +1,16 @@
+import type { ToolComposition } from './types.js';
+/**
+ * Every catalog operation usable as a COMPOSER STEP, with the composition contract it declared.
+ *
+ * Presence is the signal: a key is here exactly when the catalog gave the tool a `composition`,
+ * and the value may legitimately be `{}`. So ask `'mail_domain_create' in compositions` — a
+ * truthiness test on `label` (or any other member) would drop a perfectly composable step.
+ *
+ * The generated file is regenerated at publish time from the live catalog, so the map tracks the
+ * platform rather than anyone's memory, and the values are carried verbatim — a key the platform
+ * adds reaches the App even before this SDK's type names it.
+ *
+ * Only a re-export: the generated file stays the single source, this narrows it to `Readonly` so
+ * a consumer cannot write into the shared object.
+ */
+export declare const compositions: Readonly<Record<string, ToolComposition>>;

package/dist/_types/runtime/types.d.ts

@@ -10,6 +10,26 @@ export interface ParamSpec {
  * is the access check's business; this SDK only transports the value it was given.
  */
 export type ToolLevel = 'read' | 'write' | 'admin';
+/**
+ * The composer contract of a catalog operation: what a workflow builder needs to offer it as a
+ * STEP. Presence of an entry in `compositions` is the whole signal — `{}` is a valid, complete
+ * declaration ("composable, nothing further to say") and is deliberately distinct from absent
+ * ("not a composer step"). Ask `name in compositions`, never `compositions[name].label != null`.
+ *
+ * Every member is optional and this SDK reads none of them — it transports the object the catalog
+ * declared, verbatim: `label` names the step in a builder, `completion_event` is the event that
+ * settles an async step, `options` are builder-level knobs, and `pii`/`secrets` name input fields
+ * a composer must handle carefully. The platform owns this schema; an index signature is
+ * deliberately absent so a consumer reads the named keys type-safely, while the GENERATED map
+ * still carries any key the platform adds (the emitter serializes the catalog object as-is).
+ */
+export interface ToolComposition {
+    label?: string;
+    completion_event?: string;
+    options?: Record<string, string>;
+    pii?: string[];
+    secrets?: string[];
+}
 /**
  * The identity of a catalog operation, carried by both a `Binding` and every generated method.
  * `operationKey` is the catalog tool name verbatim (`mail_domains_create`), which is what an

package/dist/index.cjs

@@ -11208,6 +11208,7 @@ var operations = {
   "waitlist_signups_list": "read",
   "workflow_health_ping": "read"
 };
+var compositions = {};
 
 // src/runtime/permission-match.ts
 var LEVELS = ["read", "write", "admin"];
@@ -11444,8 +11445,12 @@ function accessReason(op) {
 // src/runtime/operations.ts
 var operations2 = operations;
 
+// src/runtime/compositions.ts
+var compositions2 = compositions;
+
 exports.LesslyApiError = LesslyApiError;
 exports.accessReason = accessReason;
+exports.compositions = compositions2;
 exports.connectStream = connectStream;
 exports.createLesslyApp = createLesslyApp;
 exports.isAccessDenied = isAccessDenied;