@runtypelabs/sdk 10.4.0 → 10.5.0

package/dist/index.cjs

@@ -43,7 +43,10 @@ __export(index_exports, {
   ClientBatchBuilder: () => ClientBatchBuilder,
   ClientEvalBuilder: () => ClientEvalBuilder,
   ClientFlowBuilder: () => ClientFlowBuilder,
+  ClientTokenDriftError: () => ClientTokenDriftError,
+  ClientTokenEnsureError: () => ClientTokenEnsureError,
   ClientTokensEndpoint: () => ClientTokensEndpoint,
+  ClientTokensNamespace: () => ClientTokensNamespace,
   CollectionsEndpoint: () => CollectionsEndpoint,
   ContextTemplatesEndpoint: () => ContextTemplatesEndpoint,
   ConversationsEndpoint: () => ConversationsEndpoint,
@@ -13415,6 +13418,196 @@ var SurfacesNamespace = class {
   }
 };
 
+// src/client-tokens-namespace.ts
+var ClientTokenEnsureError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ClientTokenEnsureError";
+  }
+};
+var ClientTokenDriftError = class extends Error {
+  constructor(name, plan) {
+    super(
+      `Client token "${name}" drifted: plan is '${plan.changes}' (changed: ${plan.changedKeys.join(", ") || "n/a"}). Re-run ensure to converge.`
+    );
+    this.name = "ClientTokenDriftError";
+    this.plan = plan;
+  }
+};
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+var sameSet = (a, b) => canonicalJson([...a].sort()) === canonicalJson([...b].sort());
+function planUpdate(definition, existing) {
+  const environment = definition.environment ?? "live";
+  if (environment !== existing.environment) {
+    throw new ClientTokenEnsureError(
+      `Client token "${definition.name}" is a ${existing.environment} token; the definition asks for ${environment}. A token environment cannot change. Rename the definition or delete the existing token.`
+    );
+  }
+  const productSurfaceId = definition.productSurfaceId ?? null;
+  if (productSurfaceId !== (existing.productSurfaceId ?? null)) {
+    throw new ClientTokenEnsureError(
+      `Client token "${definition.name}" belongs to surface ${existing.productSurfaceId ?? "(none)"}; the definition names ${productSurfaceId ?? "(none)"}. A token's surface cannot change.`
+    );
+  }
+  const flowIds = definition.flowIds ?? [];
+  if (flowIds.length === 0 && existing.flowIds.length > 0) {
+    throw new ClientTokenEnsureError(
+      `Client token "${definition.name}" carries flows (${existing.flowIds.join(", ")}); the API cannot remove every flow from a token. Delete the token and re-run ensure.`
+    );
+  }
+  const patch = {};
+  const agentIds = definition.agentIds ?? [];
+  if (!sameSet(agentIds, existing.agentIds)) patch.agentIds = agentIds;
+  if (flowIds.length > 0 && !sameSet(flowIds, existing.flowIds)) patch.flowIds = flowIds;
+  if (definition.defaultFlowId !== void 0 && definition.defaultFlowId !== existing.defaultFlowId) {
+    patch.defaultFlowId = definition.defaultFlowId;
+  }
+  if (!sameSet(definition.allowedOrigins, existing.allowedOrigins)) {
+    patch.allowedOrigins = definition.allowedOrigins;
+  }
+  const targetAlias = definition.targetAlias ?? null;
+  if (targetAlias !== (existing.targetAlias ?? null)) patch.targetAlias = targetAlias;
+  const targetVersionId = definition.targetVersionId ?? null;
+  if (targetVersionId !== (existing.targetVersionId ?? null)) {
+    patch.targetVersionId = targetVersionId;
+  }
+  const optionalKeys = [
+    "rateLimitPerMinute",
+    "rateLimitPerHour",
+    "maxMessagesPerSession",
+    "sessionIdleTimeoutMinutes"
+  ];
+  for (const key of optionalKeys) {
+    const desired = definition[key];
+    if (desired !== void 0 && desired !== existing[key]) patch[key] = desired;
+  }
+  if (definition.config !== void 0 && canonicalJson(definition.config) !== canonicalJson(existing.config ?? {})) {
+    patch.config = definition.config;
+  }
+  return patch;
+}
+var ClientTokensNamespace = class {
+  constructor(getClient) {
+    this.getClient = getClient;
+  }
+  async list() {
+    const response = await this.getClient().get("/client-tokens");
+    return response.clientTokens;
+  }
+  async get(id) {
+    const response = await this.getClient().get(
+      `/client-tokens/${id}`
+    );
+    return response.clientToken;
+  }
+  /** The response's `token` is the publishable value. */
+  async create(data) {
+    return this.getClient().post("/client-tokens", data);
+  }
+  async update(id, data) {
+    return this.getClient().put(
+      `/client-tokens/${id}`,
+      data
+    );
+  }
+  async delete(id) {
+    await this.getClient().delete(`/client-tokens/${id}`);
+  }
+  /** Issue a new value; the previous value stops working immediately. */
+  async regenerate(id) {
+    return this.getClient().post(`/client-tokens/${id}/regenerate`);
+  }
+  /** Read a stored token value. Fails for a reveal-once live token. */
+  async getToken(id) {
+    return this.getClient().get(`/client-tokens/${id}/token`);
+  }
+  async listConversations(id, params) {
+    return this.getClient().get(
+      `/client-tokens/${id}/conversations`,
+      params
+    );
+  }
+  /**
+   * Find the token named `definition.name`, create it when missing, and update
+   * it when it differs. Never deletes or regenerates. Throws when two tokens
+   * share the name, or when the environment or surface differs.
+   *
+   * @example
+   * ```typescript
+   * const agent = await Runtype.agents.ensure(docsAgent, { deploy: { alias: 'live' } })
+   * const { token } = await Runtype.clientTokens.ensure({
+   *   name: 'Docs site widget',
+   *   agentIds: [agent.agentId],
+   *   allowedOrigins: ['https://docs.example.com'],
+   * })
+   * ```
+   */
+  async ensure(definition, options = {}) {
+    if (typeof definition?.name !== "string" || definition.name.length === 0) {
+      throw new ClientTokenEnsureError('clientTokens.ensure requires a non-empty string "name"');
+    }
+    const dryRun = options.dryRun === true || options.expectNoChanges === true;
+    const matches = (await this.list()).filter((token) => token.name === definition.name);
+    if (matches.length > 1) {
+      throw new ClientTokenEnsureError(
+        `${matches.length} client tokens are named "${definition.name}" (${matches.map((t) => t.id).join(", ")}). Rename or delete all but one so ensure has a single identity to converge.`
+      );
+    }
+    const existing = matches[0];
+    if (!existing) {
+      const plan = { result: "plan", changes: "create", changedKeys: [] };
+      if (options.expectNoChanges) throw new ClientTokenDriftError(definition.name, plan);
+      if (dryRun) return plan;
+      const created = await this.create({ ...definition });
+      return {
+        result: "created",
+        clientToken: created.clientToken,
+        token: created.token,
+        changedKeys: [],
+        warnings: created.warnings ?? []
+      };
+    }
+    const patch = planUpdate(definition, existing);
+    const changedKeys = Object.keys(patch);
+    if (dryRun) {
+      const plan = {
+        result: "plan",
+        changes: changedKeys.length > 0 ? "update" : "none",
+        changedKeys,
+        clientToken: existing
+      };
+      if (options.expectNoChanges && plan.changes !== "none") {
+        throw new ClientTokenDriftError(definition.name, plan);
+      }
+      return plan;
+    }
+    if (changedKeys.length === 0) {
+      return {
+        result: "unchanged",
+        clientToken: existing,
+        token: existing.tokenValue,
+        changedKeys,
+        warnings: []
+      };
+    }
+    const updated = await this.update(existing.id, patch);
+    return {
+      result: "updated",
+      clientToken: updated.clientToken,
+      token: updated.clientToken.tokenValue,
+      changedKeys,
+      warnings: updated.warnings ?? []
+    };
+  }
+};
+
 // src/runtype.ts
 var globalConfig = {};
 var globalClient = null;
@@ -13961,6 +14154,24 @@ var Runtype = class {
   static get surfaces() {
     return new SurfacesNamespace(() => this.getClient());
   }
+  /**
+   * Client tokens — publishable credentials for widgets. `ensure` finds a token
+   * by name, creates it when missing, and converges its agents, flows, origins,
+   * and target; it returns the token value when the token stores one.
+   *
+   * @example
+   * ```typescript
+   * const agent = await Runtype.agents.ensure(docsAgent, { deploy: { alias: 'live' } })
+   * const { token } = await Runtype.clientTokens.ensure({
+   *   name: 'Docs site widget',
+   *   agentIds: [agent.agentId],
+   *   allowedOrigins: ['https://docs.example.com'],
+   * })
+   * ```
+   */
+  static get clientTokens() {
+    return new ClientTokensNamespace(() => this.getClient());
+  }
 };
 
 // src/agent-promotion.ts
@@ -14154,7 +14365,7 @@ function transformQueryParams(params) {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "10.4.0".length > 0 ? "10.4.0" : FALLBACK_VERSION;
+var SDK_VERSION = "10.5.0".length > 0 ? "10.5.0" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 
@@ -15446,7 +15657,10 @@ var STEP_TYPE_TO_METHOD = {
   ClientBatchBuilder,
   ClientEvalBuilder,
   ClientFlowBuilder,
+  ClientTokenDriftError,
+  ClientTokenEnsureError,
   ClientTokensEndpoint,
+  ClientTokensNamespace,
   CollectionsEndpoint,
   ContextTemplatesEndpoint,
   ConversationsEndpoint,