@firststep-studio/sdk 0.19.0 → 0.21.0

package/README.md

@@ -39,30 +39,235 @@ createServer(handler, {
 
 See `llms.txt` for full API specification.
 
-## Release notes
-
-### 0.19.0
-
-- **Cohere model support.** `llm.generate` and `llm.generateStream` accept
-  `provider: 'cohere'` with a `command-*` model (Command A, Command A+,
-  Command R, Command R+, Command R7B), routed through Studio's `/api/llm/*`
-  proxy the same way Gemini requests are. Text generation, JSON output,
-  streaming, finish reasons and token usage are supported. Gemini-only
-  features (explicit prompt caches, thinking/safety settings, image parts,
-  function-calling payloads) are outside the Cohere adapter's contract.
-- **Observable SSE stream errors.** `generateStream` only ever skipped a
-  chunk it could not parse as JSON at all (stray SSE comments/heartbeats). A
-  vendor error frame is valid JSON, so it used to be yielded as an ordinary
-  stream value, a plain object with an `error` field, indistinguishable from
-  a successful chunk to anything not inspecting its shape, so a failed turn
-  could look like a normal (if malformed) reply. A chunk shaped as an error
-  now throws `LLMError` instead of being yielded as data, with `status`
-  normalized to a numeric HTTP status: Gemini's numeric `code` or Cohere's
-  numeric `status` field is used when present, otherwise `502`. This throw
-  happens on the `.next()` call that reaches the error frame, not when
-  `generateStream()` creates the generator, so the `try/catch` must wrap the
-  entire iteration (the whole `for await` loop, or every subsequent manual
-  `.next()` call) and not just the call that obtains the stream.
-- **Handler adoption required.** Handler must upgrade to this SDK version to
-  pick up both changes. Existing Gemini configurations keep their current
-  defaults.
+## Session failure handling
+
+For external handlers with Studio session capability, `context.session` rejects
+HTTP failures, network failures, invalid JSON and unsuccessful response envelopes.
+Errors identify the session operation and include the HTTP status when available.
+The SDK does not log these errors; callers own logging and recovery. Network errors
+retain their original cause, while HTTP bodies and JSON parser details are omitted.
+On an HTTP failure, the SDK also makes a best-effort attempt to cancel the
+response body before throwing, to release the upstream connection promptly; a
+failed cancellation never replaces or masks the HTTP error, and is never logged.
+
+Await reads and writes that the next turn depends on. A rejected read must not be
+interpreted as a fresh session, and a rejected write must not be acknowledged as
+saved. An acknowledged empty session still uses the existing initialization
+behavior. Session state remains ephemeral; durable storage is a separate resource.
+
+This contract only covers what the SDK itself can see: HTTP, network and
+protocol-envelope failures on the request the SDK made. It says nothing about
+what happens upstream inside Studio's protocol-resources API before that
+response is produced. In particular, Studio's `ProtocolSessionService` falls
+back from Redis to a process-local in-memory store when Redis is unavailable
+or a Redis call fails mid-request, and that fallback still returns a normal,
+successful HTTP response, so the SDK cannot detect that it happened.
+`context.session` is ephemeral by design even when Redis is healthy, so the
+fallback is not a loss of some durability guarantee that otherwise existed.
+Its concrete effect is different: while it is active, the handler's existing
+Redis-held session state and message history become unreachable, so a
+session that already exists in Redis can read back as if it were fresh and
+empty; and any reads or writes served from the in-memory store are not
+shared across other backend processes and do not survive a restart of the
+process that served them. Follow-up: [TLE-672](https://linear.app/throughlinecare/issue/TLE-672/make-redis-session-fallback-visible-to-callers).
+
+## Publishing a release
+
+Publishing to npm is a GitHub Actions button, not a local command:
+
+1. Bump `version` in `packages/sdk/package.json` through a normal reviewed PR
+   and merge it to `main`. This workflow never edits that file itself.
+2. On `main`, go to Actions > "Publish SDK" > Run workflow, and enter the
+   exact version just merged (e.g. `0.21.0`).
+3. The workflow runs three jobs: `validate` (builds, typechecks, runs the
+   full test suite, and packs the tarball that will actually be published),
+   `publish` (ships that exact tarball to npm), and `verify` (confirms the
+   registry serves that version as `latest` with matching integrity, and
+   writes a summary).
+
+A dispatch from anything but `main` fails fast, in `validate`'s first step,
+with a message naming the problem ref. That check alone is **not** the
+security boundary, and should not be read as one: `workflow_dispatch` runs
+the workflow file checked out from whichever ref the dispatcher selects, so a
+dispatch from another branch would run that branch's own copy of this file,
+which could simply have had the check edited out. The actual security
+boundary is the `sdk-production` GitHub Environment's deployment branch rule
+(described under "One-time setup" below), which restricts which branch can
+reach the `publish` job's `id-token: write` permission at all, independent of
+anything in the workflow YAML itself. **The `sdk-production` environment now
+exists, with its custom branch policy restricting it to `main` confirmed
+configured.** Required reviewers are not configured on the environment:
+adding one through the GitHub API returned a 422, because this private
+repository's billing plan does not support required reviewers on
+environments. `workflow_dispatch` can itself be triggered either from the
+Actions UI or via the GitHub API, so it is not exclusively a human action on
+its own; the control this design relies on is that maintainers dispatch it
+manually, as intended, with the version input and the main-only branch
+restriction as the checks that run. Per current owner decision, a separate
+GitHub-enforced required-reviewers step on the environment is not required
+for using this workflow; that remains the current policy, not a claim about
+what was intended or required previously.
+
+The workflow always builds and publishes the exact commit that was
+dispatched (`github.sha`), not whatever `main` points to by the time the run
+reaches the `publish` job. That way a later push to `main` during a long
+approval wait cannot change what ships. It refuses a version that does not
+match the committed manifest, refuses a version already on the registry, and
+refuses moving the `latest` dist-tag backwards; it re-checks those last two
+immediately before publishing too, in case the approval wait let someone
+else ship a release in the meantime. This workflow targets an existing,
+already-published package only, so an empty or malformed registry read
+(including a bare `{}` on an HTTP 200) is always refused rather than read as
+"nothing published yet"; it has no first-ever-release path. The policy
+checks live in `scripts/sdk-publish-policy.mjs`
+(unit-tested in `scripts/sdk-publish-policy.test.mjs`); the workflow calls
+them through the thin CLI wrapper `scripts/sdk-publish-cli.mjs`
+(unit-tested in `scripts/sdk-publish-cli.test.mjs`).
+
+The "refuses moving `latest` backwards" rule is deliberately strict:
+**`latest` only ever moves forward, monotonically, by whatever version was
+most recently merged and dispatched.** There is no supported path through
+this workflow for publishing a patch onto an older release line once a newer
+one is `latest` (e.g. shipping `0.19.5` as a backport fix after `0.21.0` is
+already out). `assertNotDowngrade` refuses that the same way it refuses an
+actual downgrade, on purpose, because the two are indistinguishable from the
+registry's dist-tags alone. If a maintenance-branch backport policy is ever
+needed, it is a separate, deliberately-designed workflow (almost certainly
+publishing to a non-`latest` dist-tag), not an extension of this one.
+
+### Registry read freshness
+
+The npm registry's packument endpoint (what `check-registry` and `verify`
+both read) sits behind a CDN that can serve a cached response for a
+noticeable window. Both call sites go through the same helper
+(`fetchPackageMeta` in `scripts/sdk-publish-cli.mjs`, built on
+`fetchJsonWithRetry` in `scripts/sdk-publish-policy.mjs`), which requests
+cache revalidation (`Cache-Control: no-cache`, `Pragma: no-cache`) **and**
+appends a cache-busting query parameter to the URL
+(`withCacheBustingParam`) on every attempt, since a CDN that keys its cache
+on request headers and one that keys on the exact URL are both real,
+observed behaviors and neither is something this code can detect or rely on
+alone. Both are best-effort: whether a given CDN honors either is outside
+this repo's control, and no claim of "always fresh" is made here or
+anywhere else in this workflow. `verify`'s own outer polling loop (distinct
+from that per-request retry) is sized with a bounded fallback in mind: it
+waits up to ~350s (`VERIFY_MAX_ATTEMPTS` * `VERIFY_DELAY_MS` in
+`scripts/sdk-publish-cli.mjs`), comfortable margin over a ~300s cache
+window, for the case neither mitigation fully bypasses the CDN.
+`check-registry` is intentionally not widened the same way: it is a quick,
+bounded gate (2-minute step timeout) run twice (once in `validate`, once
+immediately before `npm publish`), not a long poll, so a CDN that ignores
+both mitigations for its full window is a residual risk there.
+
+That residual risk is **not** symmetric, and `verify` does not backstop
+both halves of it the same way. A stale `check-registry` read that hides an
+already-published `REQUESTED` is caught at actual publish time: npm itself
+refuses to publish over a version number that already exists, independent
+of anything this workflow read beforehand. A stale read that hides a
+*newer* `latest` than `check-registry` saw is not caught anywhere after the
+fact: `npm publish --tag latest` unconditionally moves the `latest`
+dist-tag to whatever was just published, with no server-side semver
+ordering check, and `verify` only confirms that `REQUESTED` becomes
+`latest`, which is trivially true immediately after any successful publish
+with that tag. So a downgrade let through by a stale pre-publish read would
+publish successfully, and `verify` would pass, having confirmed the publish
+happened, not that it was the right thing to publish. The realistic
+exposure is narrow: this workflow's `concurrency: group: publish-sdk`
+setting means no two runs of this workflow can race each other, so the only
+way a stale read here actually causes a downgrade is an `npm publish`
+bypassing this workflow entirely, out of band, which is already a process
+violation this code cannot fully close through registry reads alone.
+
+Before publishing, `validate` also extracts the packed tarball and checks it
+has the files the package is supposed to ship, that every file declared in
+`package.json`'s `main`/`module`/`types`/`exports` actually resolves to a
+file in the tarball, that its `package.json` name and version match what was
+approved, and that both the CommonJS and ESM build of both public entry
+points (the root export and `./server`) actually load. After publishing, `verify` polls the registry
+until the version is live and compares three independent copies of the same
+bytes: the registry's own `dist.integrity` metadata, the local tarball
+`validate` built and tested, and the tarball actually downloaded from the
+registry. It fails if any of them disagree.
+
+That download is itself size-bounded (`downloadTarballWithLimit` in
+`scripts/sdk-publish-policy.mjs`): it reads the response as a stream, hashing
+incrementally and counting actual bytes as they arrive, and aborts the moment
+the running total crosses a generous but finite ceiling
+(`MAX_TARBALL_BYTES`, 50 MiB against an actual packed size of a few hundred
+KB) rather than buffering an unbounded response into memory first. A declared
+`Content-Length` over that ceiling is refused before any body bytes are read;
+a missing or understated one does not grant an exemption, since the limit is
+also enforced from the streamed byte count directly; and a declared length
+that does not match the actual streamed count at all is refused too, even
+when both are within the ceiling. The tarball URL's host is also checked
+against the configured registry before anything is fetched.
+
+Publishing uses npm's
+[trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC): the
+`publish` job exchanges a short-lived GitHub Actions `id-token` for a
+publish credential directly with npm. There is no `NPM_TOKEN` secret
+anywhere in this flow. This requires npm >= 11.5.1 and Node >= 22.14.0; Node
+22 ships an older bundled npm (22.23.2 ships 10.9.8), so both `validate` and
+`publish` install a pinned, compatible npm (currently 11.21.0) right after
+`actions/setup-node`, and the actual installed versions are checked against
+those floors rather than assumed.
+
+### If publish succeeds but verify fails
+
+Do not re-run the workflow with the same version. `npm publish` has already
+happened and is immutable; re-dispatching the same version will correctly be
+refused by the already-published check, which is a symptom of the situation,
+not a way to retry it. Instead check the registry by hand
+(`npm view @firststep-studio/sdk`) to see what actually landed, find out why
+`verify` disagreed (a slow registry propagation is recoverable by re-running
+just the `verify` job; a genuine integrity mismatch is not and needs
+investigation before anything else is published). If a corrected release is
+still needed, it goes out as the next version through the normal PR + bump +
+dispatch flow, not a republish of the one that already shipped.
+
+### One-time setup this workflow depends on (partially done)
+
+Trusted publishing and the production environment are both configured on
+npmjs.com and github.com, outside this repo's source, and are not something a
+PR can set up:
+
+- On npmjs.com, under the `@firststep-studio/sdk` package's trusted
+  publisher settings, add a GitHub Actions trusted publisher with:
+  - Organization or user: `ThroughLineCare`
+  - Repository: `firststep-studio`
+  - Workflow filename: `publish-sdk.yml`. Use **the bare filename only**,
+    not the `.github/workflows/` path. npm's trusted-publisher form matches
+    on filename, not path.
+  - Environment name: `sdk-production`
+
+  All four have to match what the workflow run actually presents, or npm
+  rejects the OIDC exchange. npm's own trusted-publishing docs state the
+  first publish from a newly configured trusted publisher must succeed
+  within 2 days of setting it up, or the configuration expires and needs to
+  be redone:
+  <https://docs.npmjs.com/trusted-publishers/#trusted-publisher-configuration-expiry>.
+  Dispatch a real publish reasonably soon after configuring this, not at an
+  arbitrary later date.
+- On github.com, under this repo's Settings > Environments: the
+  `sdk-production` environment **now exists**, with its custom deployment
+  branch policy restricting it to `main` confirmed configured. This
+  environment's deployment branch rule is the actual security boundary
+  described above under "Publishing a release", and that half is in place.
+  **Required reviewers are not configured**: adding one through the GitHub
+  API returned HTTP 422, because this private repository's current billing
+  plan does not support required reviewers on environments. `workflow_dispatch`
+  can be invoked via the API as well as the UI, so the control this design
+  relies on is that maintainers dispatch it manually, as the workflow is
+  intended to be used, with the version-input and main-only-branch checks
+  that run on every dispatch. Per current owner decision, a separate
+  required-reviewers approval step on the environment is not required to use
+  this workflow; if the billing plan changes later, adding one would be an
+  additional, optional layer on top of this policy.
+- This repository is **private** (confirmed via `gh repo view`). Per npm's
+  trusted-publishing docs, provenance attestations are not generated for a
+  trusted-publish from a private repository, because the attestation depends
+  on a publicly fetchable build log. The `publish` job sets
+  `NPM_CONFIG_PROVENANCE=false` explicitly so this is a deliberate no-op
+  rather than a failure partway through a publish. If this repository is
+  ever made public, provenance can be enabled by removing that environment
+  variable from the `publish` job.

package/dist/index.d.mts

@@ -354,6 +354,16 @@ interface PlatformChatbotRegisterInput {
         [key: string]: unknown;
     };
 }
+/** Whether a bot's deployment runs the age and consent onboarding, with a link to show it. */
+interface PlatformDeploymentPreview {
+    /** True when the deployment's web chat shows the onboarding. */
+    onboardingEnabled: boolean;
+    deploymentSlug: string;
+    /** Opens the onboarding without a Studio login. Null when the onboarding is off. */
+    previewUrl: string | null;
+    /** ISO time the link stops working (30 minutes). Null when the onboarding is off. */
+    expiresAt: string | null;
+}
 interface PlatformChatbotRegistration {
     /** Studio chatbot MongoDB ID (immutable across re-registrations). */
     id: string;
@@ -571,6 +581,13 @@ declare class PlatformClient {
      * can call this on every config save without creating duplicates.
      */
     registerChatbot(input: PlatformChatbotRegisterInput): Promise<PlatformChatbotRegistration>;
+    /**
+     * Ask whether the deployment of the chatbot identified by `externalId` runs
+     * the age and consent onboarding and, if so, get a fresh preview link to it.
+     * Each call with the onboarding on mints a new 30-minute link, so call it
+     * when the link is needed rather than caching the result.
+     */
+    getDeploymentPreview(externalId: string): Promise<PlatformDeploymentPreview>;
     /**
      * Mark the chatbot identified by `externalId` as disconnected.
      * The Studio record is preserved (history, analytics survive).
@@ -1365,4 +1382,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type HelplineCardV2Item, type HelplineCardV2Payload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type RecommendationKind, type RecommendedItem, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type ThroughlineV2ContactMethod, type ThroughlineV2Country, type ThroughlineV2Description, type ThroughlineV2Helpline, type ThroughlineV2HelplinesQuery, type ThroughlineV2HelplinesResponse, type ThroughlineV2OpeningSpan, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, extractRecommendedItems, isValidToken, parseMarkerPayload, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type HelplineCardV2Item, type HelplineCardV2Payload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, type PlatformDeploymentPreview, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type RecommendationKind, type RecommendedItem, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type ThroughlineV2ContactMethod, type ThroughlineV2Country, type ThroughlineV2Description, type ThroughlineV2Helpline, type ThroughlineV2HelplinesQuery, type ThroughlineV2HelplinesResponse, type ThroughlineV2OpeningSpan, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, extractRecommendedItems, isValidToken, parseMarkerPayload, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.d.ts

@@ -354,6 +354,16 @@ interface PlatformChatbotRegisterInput {
         [key: string]: unknown;
     };
 }
+/** Whether a bot's deployment runs the age and consent onboarding, with a link to show it. */
+interface PlatformDeploymentPreview {
+    /** True when the deployment's web chat shows the onboarding. */
+    onboardingEnabled: boolean;
+    deploymentSlug: string;
+    /** Opens the onboarding without a Studio login. Null when the onboarding is off. */
+    previewUrl: string | null;
+    /** ISO time the link stops working (30 minutes). Null when the onboarding is off. */
+    expiresAt: string | null;
+}
 interface PlatformChatbotRegistration {
     /** Studio chatbot MongoDB ID (immutable across re-registrations). */
     id: string;
@@ -571,6 +581,13 @@ declare class PlatformClient {
      * can call this on every config save without creating duplicates.
      */
     registerChatbot(input: PlatformChatbotRegisterInput): Promise<PlatformChatbotRegistration>;
+    /**
+     * Ask whether the deployment of the chatbot identified by `externalId` runs
+     * the age and consent onboarding and, if so, get a fresh preview link to it.
+     * Each call with the onboarding on mints a new 30-minute link, so call it
+     * when the link is needed rather than caching the result.
+     */
+    getDeploymentPreview(externalId: string): Promise<PlatformDeploymentPreview>;
     /**
      * Mark the chatbot identified by `externalId` as disconnected.
      * The Studio record is preserved (history, analytics survive).
@@ -1365,4 +1382,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type HelplineCardV2Item, type HelplineCardV2Payload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type RecommendationKind, type RecommendedItem, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type ThroughlineV2ContactMethod, type ThroughlineV2Country, type ThroughlineV2Description, type ThroughlineV2Helpline, type ThroughlineV2HelplinesQuery, type ThroughlineV2HelplinesResponse, type ThroughlineV2OpeningSpan, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, extractRecommendedItems, isValidToken, parseMarkerPayload, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type HelplineCardV2Item, type HelplineCardV2Payload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, type PlatformDeploymentPreview, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type RecommendationKind, type RecommendedItem, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type ThroughlineV2ContactMethod, type ThroughlineV2Country, type ThroughlineV2Description, type ThroughlineV2Helpline, type ThroughlineV2HelplinesQuery, type ThroughlineV2HelplinesResponse, type ThroughlineV2OpeningSpan, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, extractRecommendedItems, isValidToken, parseMarkerPayload, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.js

@@ -742,6 +742,19 @@ var PlatformClient = class {
       { method: "POST", body: input }
     );
   }
+  /**
+   * Ask whether the deployment of the chatbot identified by `externalId` runs
+   * the age and consent onboarding and, if so, get a fresh preview link to it.
+   * Each call with the onboarding on mints a new 30-minute link, so call it
+   * when the link is needed rather than caching the result.
+   */
+  async getDeploymentPreview(externalId) {
+    return this.request(
+      `/api/protocol/chatbots/${encodeURIComponent(externalId)}/preview`,
+      "Failed to get deployment preview",
+      { method: "POST" }
+    );
+  }
   /**
    * Mark the chatbot identified by `externalId` as disconnected.
    * The Studio record is preserved (history, analytics survive).