@runtypelabs/sdk 4.14.0 → 4.15.0

package/dist/index.mjs

@@ -1094,20 +1094,20 @@ var FlowBuilder = class {
    */
   build() {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request3 = { flow };
+    const request4 = { flow };
     if (this.recordConfig) {
-      request3.record = this.recordConfig;
+      request4.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request3.messages = this.messagesConfig;
+      request4.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request3.inputs = this.inputsConfig;
+      request4.inputs = this.inputsConfig;
     }
     if (Object.keys(this.optionsConfig).length > 0) {
-      request3.options = this.optionsConfig;
+      request4.options = this.optionsConfig;
     }
-    return request3;
+    return request4;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -2501,15 +2501,15 @@ var RuntypeFlowBuilder = class {
   build() {
     const flowMode = this.mode === "existing" ? "existing" : this.mode;
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
-    const request3 = { flow };
+    const request4 = { flow };
     if (this.recordConfig) {
-      request3.record = this.recordConfig;
+      request4.record = this.recordConfig;
     }
     if (this.messagesConfig) {
-      request3.messages = this.messagesConfig;
+      request4.messages = this.messagesConfig;
     }
     if (this.inputsConfig) {
-      request3.inputs = this.inputsConfig;
+      request4.inputs = this.inputsConfig;
     }
     const options = {
       flowMode,
@@ -2527,8 +2527,8 @@ var RuntypeFlowBuilder = class {
     if (this.mode === "upsert" && Object.keys(this.upsertOptions).length > 0) {
       options.upsertOptions = this.upsertOptions;
     }
-    request3.options = options;
-    return request3;
+    request4.options = options;
+    return request4;
   }
   /**
    * Validate this prospective flow against the public validation endpoint
@@ -3809,6 +3809,219 @@ var ToolsNamespace = class {
   }
 };
 
+// src/products-ensure.ts
+function isPlainObject4(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeValue3(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeValue3(item));
+  }
+  if (isPlainObject4(value)) {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === void 0 || entry === null) continue;
+      normalized[key] = normalizeValue3(entry);
+    }
+    return normalized;
+  }
+  return value;
+}
+function normalizeProductDefinition(definition) {
+  const spec = isPlainObject4(definition.spec) ? normalizeValue3(definition.spec) : {};
+  return {
+    ...definition.description ? { description: definition.description } : {},
+    ...definition.icon ? { icon: definition.icon } : {},
+    spec
+  };
+}
+async function computeProductContentHash(definition) {
+  const serialized = JSON.stringify(normalizeProductDefinition(definition));
+  const encoded = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var DEFINE_PRODUCT_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["name", "description", "icon", "spec"]);
+function defineProduct(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("defineProduct requires a definition object");
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    throw new Error('defineProduct requires a non-empty string "name"');
+  }
+  if (input.description != null && typeof input.description !== "string") {
+    throw new Error('defineProduct "description" must be a string when provided');
+  }
+  if (input.icon != null && typeof input.icon !== "string") {
+    throw new Error('defineProduct "icon" must be a string when provided');
+  }
+  if (input.spec != null && !isPlainObject4(input.spec)) {
+    throw new Error('defineProduct "spec" must be an object when provided');
+  }
+  const unknownKeys = Object.keys(input).filter((key) => !DEFINE_PRODUCT_TOP_LEVEL_KEYS.has(key));
+  if (unknownKeys.length > 0) {
+    throw new Error(
+      `defineProduct: unknown field(s): ${unknownKeys.join(", ")}. Allowed fields are name, description, icon, spec. (canvas / nested capabilities and surfaces are not converged by ensure.)`
+    );
+  }
+  return {
+    name: input.name,
+    ...input.description !== void 0 ? { description: input.description } : {},
+    ...input.icon !== void 0 ? { icon: input.icon } : {},
+    ...input.spec !== void 0 ? { spec: input.spec } : {}
+  };
+}
+var ProductEnsureConflictError = class extends Error {
+  constructor(body) {
+    super(body.error ?? `Product ensure conflict: ${body.code}`);
+    this.name = "ProductEnsureConflictError";
+    this.code = body.code;
+    this.lastModifiedSource = body.lastModifiedSource;
+    this.modifiedAt = body.modifiedAt;
+    this.currentHash = body.currentHash;
+  }
+};
+var ProductDriftError = class extends Error {
+  constructor(plan) {
+    super(
+      `Product "${plan.productId ?? "definition"}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Run client.products.pull(name) to absorb the remote edit into your repo, or re-run ensure to converge.`
+    );
+    this.name = "ProductDriftError";
+    this.plan = plan;
+  }
+};
+function parseRequestError4(err) {
+  if (!(err instanceof Error)) return { status: null, body: null };
+  const match = err.message.match(/^API request failed: (\d{3}) .*? - ([\s\S]*)$/);
+  if (!match) return { status: null, body: null };
+  try {
+    return { status: Number(match[1]), body: JSON.parse(match[2]) };
+  } catch {
+    return { status: Number(match[1]), body: null };
+  }
+}
+function toConflictError4(err) {
+  const { status, body } = parseRequestError4(err);
+  if (status !== 409 || !isPlainObject4(body)) return null;
+  const code = body.code;
+  if (code !== "external_modification" && code !== "remote_changed") return null;
+  return new ProductEnsureConflictError(
+    body
+  );
+}
+var serverHashMemo4 = /* @__PURE__ */ new WeakMap();
+function memoFor4(client) {
+  let memo = serverHashMemo4.get(client);
+  if (!memo) {
+    memo = /* @__PURE__ */ new Map();
+    serverHashMemo4.set(client, memo);
+  }
+  return memo;
+}
+function memoize3(memo, memoKey, result) {
+  if (result.result !== "plan") memo.set(memoKey, result.contentHash);
+}
+async function request3(client, body) {
+  try {
+    return await client.post(
+      "/products/ensure",
+      body
+    );
+  } catch (err) {
+    const conflict = toConflictError4(err);
+    if (conflict) throw conflict;
+    throw err;
+  }
+}
+async function ensureProduct(client, definition, options = {}) {
+  const { dryRun, onConflict, expectedRemoteHash, expectNoChanges } = options;
+  const passthrough = {
+    ...onConflict ? { onConflict } : {},
+    ...expectedRemoteHash ? { expectedRemoteHash } : {}
+  };
+  if (dryRun || expectNoChanges) {
+    const plan = await request3(client, {
+      name: definition.name,
+      definition,
+      dryRun: true,
+      ...passthrough
+    });
+    if (plan.result !== "plan") {
+      throw new Error(`Expected a plan result from dryRun, got '${plan.result}'`);
+    }
+    if (expectNoChanges && plan.changes !== "none") {
+      throw new ProductDriftError(plan);
+    }
+    return plan;
+  }
+  const memo = memoFor4(client);
+  const localHash = await computeProductContentHash(definition);
+  const memoKey = `${definition.name} ${localHash}`;
+  const contentHash = memo.get(memoKey) ?? localHash;
+  const probe = await request3(client, {
+    name: definition.name,
+    contentHash,
+    ...passthrough
+  });
+  if (probe.result !== "definitionRequired") {
+    memoize3(memo, memoKey, probe);
+    return probe;
+  }
+  const converged = await request3(client, {
+    name: definition.name,
+    definition,
+    ...passthrough
+  });
+  if (converged.result === "definitionRequired") {
+    throw new Error("Server reported definitionRequired for a full-definition request");
+  }
+  memoize3(memo, memoKey, converged);
+  return converged;
+}
+async function pullProduct(client, name) {
+  return client.get("/products/pull", { name });
+}
+
+// src/products-namespace.ts
+var ProductsNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  /**
+   * Idempotently converge a `defineProduct` definition onto the platform.
+   * Hash-first: the steady state is one tiny probe request. Creates or updates
+   * the top-level product record; never deletes. Identity is name + account
+   * scope.
+   *
+   * @example
+   * ```typescript
+   * const product = defineProduct({
+   *   name: 'Support Copilot',
+   *   description: 'An AI support assistant',
+   *   icon: '🤖',
+   *   spec: { productGoal: 'Deflect tier-1 tickets', productStage: 'beta' },
+   * })
+   *
+   * // Converge (CI/deploy).
+   * const result = await Runtype.products.ensure(product)
+   *
+   * // PR drift gate.
+   * await Runtype.products.ensure(product, { expectNoChanges: true })
+   * ```
+   */
+  async ensure(definition, options = {}) {
+    return ensureProduct(this.getClient(), definition, options);
+  }
+  /**
+   * Pull the canonical definition + provenance for a product by name — the
+   * absorb-drift direction of the ensure protocol.
+   */
+  async pull(name) {
+    return pullProduct(this.getClient(), name);
+  }
+};
+
 // src/transform.ts
 function transformResponse(data) {
   return data;
@@ -4225,6 +4438,37 @@ var Runtype = class {
   static get tools() {
     return new ToolsNamespace(() => this.getClient());
   }
+  /**
+   * Products namespace - Product config-as-code (define / ensure / pull)
+   *
+   * Converges the top-level product record (description, icon, spec). Nested
+   * capabilities/surfaces/tools and the canvas UI layout state are not
+   * converged by ensure.
+   *
+   * @example
+   * ```typescript
+   * import { defineProduct, Runtype } from '@runtypelabs/sdk'
+   *
+   * const product = defineProduct({
+   *   name: 'Support Copilot',
+   *   description: 'An AI support assistant',
+   *   icon: '🤖',
+   *   spec: { productGoal: 'Deflect tier-1 tickets', productStage: 'beta' },
+   * })
+   *
+   * // Converge at deploy time (idempotent; one tiny probe in steady state)
+   * await Runtype.products.ensure(product)
+   *
+   * // CI drift gate
+   * await Runtype.products.ensure(product, { expectNoChanges: true })
+   *
+   * // Absorb a dashboard edit back into the repo
+   * const { definition } = await Runtype.products.pull('Support Copilot')
+   * ```
+   */
+  static get products() {
+    return new ProductsNamespace(() => this.getClient());
+  }
 };
 
 // src/generated-tool-gate.ts
@@ -4447,8 +4691,8 @@ function buildGeneratedRuntimeToolGateOutput(proposal, options = {}) {
     ...decision.tool ? { tool: decision.tool } : {}
   };
 }
-function attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options = {}) {
-  const stepList = request3.flow.steps;
+function attachRuntimeToolsToDispatchRequest(request4, runtimeTools, options = {}) {
+  const stepList = request4.flow.steps;
   if (!stepList || !Array.isArray(stepList) || stepList.length === 0) {
     throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
   }
@@ -4491,9 +4735,9 @@ function attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options = {
     }
   };
   return {
-    ...request3,
+    ...request4,
     flow: {
-      ...request3.flow,
+      ...request4.flow,
       // `clonedSteps` is a structural clone of `request.flow.steps` (already
       // `FlowStepDefinition[]`); only the prompt step's `config.tools` was
       // merged, so every step's `type` discriminant is preserved. The clone is
@@ -4503,12 +4747,12 @@ function attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options = {
     }
   };
 }
-function applyGeneratedRuntimeToolProposalToDispatchRequest(request3, proposal, options = {}) {
+function applyGeneratedRuntimeToolProposalToDispatchRequest(request4, proposal, options = {}) {
   const decision = evaluateGeneratedRuntimeToolProposal(proposal, options.gate);
   if (!decision.approved || !decision.tool) {
-    return { decision, request: request3 };
+    return { decision, request: request4 };
   }
-  const nextRequest = attachRuntimeToolsToDispatchRequest(request3, [decision.tool], options.attach);
+  const nextRequest = attachRuntimeToolsToDispatchRequest(request4, [decision.tool], options.attach);
   return {
     decision,
     request: nextRequest
@@ -6758,15 +7002,15 @@ var DispatchEndpoint = class {
    * Attach approved runtime tools to a prompt step in a redispatch request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request3, runtimeTools, options) {
-    return attachRuntimeToolsToDispatchRequest(request3, runtimeTools, options);
+  attachApprovedRuntimeTools(request4, runtimeTools, options) {
+    return attachRuntimeToolsToDispatchRequest(request4, runtimeTools, options);
   }
   /**
    * Validate a generated runtime tool proposal and attach it to the redispatch
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request3, proposal, options) {
-    return applyGeneratedRuntimeToolProposalToDispatchRequest(request3, proposal, options);
+  applyGeneratedRuntimeToolProposal(request4, proposal, options) {
+    return applyGeneratedRuntimeToolProposalToDispatchRequest(request4, proposal, options);
   }
 };
 var ChatEndpoint = class {
@@ -7318,8 +7562,8 @@ var GENERATED_RUNTIME_TOOL_PROPOSAL_SCHEMA = {
   },
   required: ["name", "description", "toolType", "parametersSchema", "config"]
 };
-function appendRuntimeToolsToAgentRequest(request3, runtimeTools) {
-  const existing = request3.tools?.runtimeTools || [];
+function appendRuntimeToolsToAgentRequest(request4, runtimeTools) {
+  const existing = request4.tools?.runtimeTools || [];
   const existingNames = new Set(existing.map((tool) => tool.name));
   const converted = runtimeTools.filter((tool) => !existingNames.has(tool.name)).map((tool) => ({
     name: tool.name,
@@ -7329,9 +7573,9 @@ function appendRuntimeToolsToAgentRequest(request3, runtimeTools) {
     ...tool.config ? { config: tool.config } : {}
   }));
   return {
-    ...request3,
+    ...request4,
     tools: {
-      ...request3.tools,
+      ...request4.tools,
       runtimeTools: [...existing, ...converted]
     }
   };
@@ -7407,21 +7651,21 @@ var _AgentsEndpoint = class _AgentsEndpoint {
    * Attach approved runtime tools to an agent execute request.
    * Returns a new request object and does not mutate the original.
    */
-  attachApprovedRuntimeTools(request3, runtimeTools) {
-    return appendRuntimeToolsToAgentRequest(request3, runtimeTools);
+  attachApprovedRuntimeTools(request4, runtimeTools) {
+    return appendRuntimeToolsToAgentRequest(request4, runtimeTools);
   }
   /**
    * Validate a generated runtime tool proposal and append it to an agent execute
    * request if approved, in one call.
    */
-  applyGeneratedRuntimeToolProposal(request3, proposal, options) {
+  applyGeneratedRuntimeToolProposal(request4, proposal, options) {
     const decision = evaluateGeneratedRuntimeToolProposal(proposal, options);
     if (!decision.approved || !decision.tool) {
-      return { decision, request: request3 };
+      return { decision, request: request4 };
     }
     return {
       decision,
-      request: appendRuntimeToolsToAgentRequest(request3, [decision.tool])
+      request: appendRuntimeToolsToAgentRequest(request4, [decision.tool])
     };
   }
   /**
@@ -10657,7 +10901,7 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  async runWithLocalTools(request3, localTools, arg3, arg4) {
+  async runWithLocalTools(request4, localTools, arg3, arg4) {
     const isOptionsObject = (val) => typeof val === "object" && val !== null && "scope" in val;
     const callbacks = isOptionsObject(arg3) ? void 0 : arg3;
     const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
@@ -10671,12 +10915,12 @@ var RuntypeClient2 = class {
       ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
     })) : [];
     const modifiedRequest = {
-      ...request3,
+      ...request4,
       ...derivedClientTools.length > 0 ? {
-        clientTools: [...request3.clientTools ?? [], ...derivedClientTools]
+        clientTools: [...request4.clientTools ?? [], ...derivedClientTools]
       } : {},
       options: {
-        ...request3.options || {},
+        ...request4.options || {},
         streamResponse: isStreaming
       }
     };
@@ -11114,20 +11358,20 @@ var BatchBuilder = class {
     if (!this.recordType) {
       throw new Error("BatchBuilder: recordType is required. Call .forRecordType(type) first.");
     }
-    const request3 = {
+    const request4 = {
       flowId: this.flowId,
       recordType: this.recordType
     };
     if (Object.keys(this.batchOptions).length > 0) {
-      request3.options = this.batchOptions;
+      request4.options = this.batchOptions;
     }
     if (this.filterConfig) {
-      request3.filter = this.filterConfig;
+      request4.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request3.limit = this.limitConfig;
+      request4.limit = this.limitConfig;
     }
-    return request3;
+    return request4;
   }
   /**
    * Execute the batch operation
@@ -11284,32 +11528,32 @@ var EvalBuilder = class {
         "EvalBuilder: records are required. Call .forRecordType(type) or .withRecords([...]) first."
       );
     }
-    const request3 = {};
+    const request4 = {};
     if (this.flowId) {
-      request3.flowId = this.flowId;
+      request4.flowId = this.flowId;
     } else if (this.virtualFlow) {
-      request3.flow = this.virtualFlow;
+      request4.flow = this.virtualFlow;
     }
     if (this.recordType) {
-      request3.recordType = this.recordType;
+      request4.recordType = this.recordType;
     } else if (this.inlineRecords) {
-      request3.records = this.inlineRecords;
+      request4.records = this.inlineRecords;
     }
     if (this.modelOverrides) {
-      request3.modelOverrides = this.modelOverrides;
+      request4.modelOverrides = this.modelOverrides;
     } else if (this.modelConfigs) {
-      request3.modelConfigs = this.modelConfigs;
+      request4.modelConfigs = this.modelConfigs;
     }
     if (Object.keys(this.evalOptions).length > 0) {
-      request3.options = this.evalOptions;
+      request4.options = this.evalOptions;
     }
     if (this.filterConfig) {
-      request3.filter = this.filterConfig;
+      request4.filter = this.filterConfig;
     }
     if (this.limitConfig !== void 0) {
-      request3.limit = this.limitConfig;
+      request4.limit = this.limitConfig;
     }
-    return request3;
+    return request4;
   }
   /**
    * Execute the evaluation
@@ -11812,6 +12056,9 @@ export {
   LEDGER_ARTIFACT_LINE_PREFIX,
   LogsEndpoint,
   ModelConfigsEndpoint,
+  ProductDriftError,
+  ProductEnsureConflictError,
+  ProductsNamespace,
   PromptRunner,
   PromptsEndpoint,
   PromptsNamespace,
@@ -11843,6 +12090,7 @@ export {
   compileWorkflowConfig,
   computeAgentContentHash,
   computeFlowContentHash,
+  computeProductContentHash,
   computeToolContentHash,
   createClient,
   createExternalTool,
@@ -11851,6 +12099,7 @@ export {
   defineAgent,
   defineFlow,
   definePlaybook,
+  defineProduct,
   defineTool,
   deployWorkflow,
   ensureDefaultWorkflowHooks,
@@ -11867,6 +12116,7 @@ export {
   listWorkflowHooks,
   normalizeAgentDefinition,
   normalizeCandidatePath,
+  normalizeProductDefinition,
   normalizeToolDefinition,
   parseFinalBuffer,
   parseLedgerArtifactRelativePath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/sdk",
-  "version": "4.14.0",
+  "version": "4.15.0",
   "type": "module",
   "description": "TypeScript SDK for the Runtype API with fluent methods. Use it to quickly realize AI products, agents, and workflows.",
   "main": "dist/index.cjs",