@curviate/sdk 0.29.0 → 0.30.0

package/dist/index.js

@@ -27,18 +27,47 @@ var ERROR_CODES = [
   // `next_action` sentence. user_fixable, never retryable as sent; re-send
   // with a chosen id.
   "FILTER_CANDIDATES_REQUIRED",
-  // Tier / subscription gating
-  "TIER_NOT_ACTIVE",
+  // Entitlement gating. THREE INDEPENDENT REFUSALS, three codes, three
+  // different remedies. Read the code, never the message, to tell them apart:
+  //
+  // - `NO_ACTIVE_SEAT`: this Curviate tenant has no active paid seat covering
+  //   the account. The remedy is billing, inside Curviate. There is no product
+  //   tier to buy: one paid seat entitles every operation, so nothing here
+  //   names a tier or asks for an upgrade.
+  // - `LINKEDIN_FEATURE_NOT_SUBSCRIBED`: the seat is fine, but the LinkedIn
+  //   account itself lacks the LinkedIn subscription the operation needs
+  //   (Sales Navigator, Recruiter). The remedy is on LinkedIn, not in
+  //   Curviate, and no amount of Curviate billing lifts it.
+  // - `BETA_NOT_ENABLED`: the operation is beta-gated and this tenant has not
+  //   consented to beta. The remedy is a human enabling beta in the dashboard,
+  //   or the per-request `X-Curviate-Beta` header. Nothing is wrong with the
+  //   seat or the LinkedIn subscription.
+  //
+  // All three are 403 and all three are user_fixable, which is exactly why the
+  // code has to carry the distinction: the messages read alike and the fixes
+  // are in three different systems.
+  "NO_ACTIVE_SEAT",
   "LINKEDIN_FEATURE_NOT_SUBSCRIBED",
+  "BETA_NOT_ENABLED",
+  /**
+   * @deprecated Replaced by {@link NO_ACTIVE_SEAT}. Product tiers are retired,
+   * so no refusal names one any more.
+   *
+   * STILL EXPORTED ON PURPOSE, and this is not a courtesy: API deployments
+   * that predate the seat-based entitlement rollout still emit this code, and
+   * a client that stopped recognising it would decode it to `INTERNAL`: a
+   * fixable billing refusal arriving as a server fault, against the very
+   * deployments most likely to send it. It is withdrawn in the first release
+   * after every deployment carries the new contract.
+   *
+   * Handle both while that is true: `NO_ACTIVE_SEAT` from a current
+   * deployment, this from an older one. They mean the same thing to a caller.
+   */
+  "TIER_NOT_ACTIVE",
   // Rate limits
   "RATE_LIMIT_ACCOUNT",
   "RATE_LIMIT_TENANT",
   "PLATFORM_RATE_LIMIT",
-  // LinkedIn-platform-level throttling on the Recruiter / Sales Navigator read
-  // surface (carries dedicated RateLimit-Policy / RateLimit / Retry-After
-  // response headers). Distinct from the account/tenant/platform trio above.
-  // Always retry-safe (retry_likely_to_succeed: true); see RETRYABLE_CODES.
-  "RATE_LIMITED",
   // Curviate's OWN account-safety ceiling, not a request-rate limit and not
   // LinkedIn refusing. A 429 that never reached LinkedIn and spent nothing:
   // the budget row named by `budgetRow` is at the ceiling configured on
@@ -62,12 +91,16 @@ var ERROR_CODES = [
   "CHECKPOINT_ALREADY_RESOLVED",
   "CHECKPOINT_UNSUPPORTED",
   "CONNECTION_IN_PROGRESS",
-  // One-premium boundary rejection: LinkedIn permits only one individual
-  // Premium subscription per profile. Surfaces on connect/reconnect (a seat
-  // resolving to both premiums) and on the billing seat/tier endpoints (a
-  // "naked enable" of one premium while the seat already holds the other).
-  // user_fixable, never retryable; the remedy is two seats, or pairing
-  // enable with disable of the current premium in one call.
+  /**
+   * @deprecated Withdrawn with no replacement. The one-premium conflict it
+   * reported cannot be expressed on the current input, because
+   * `linkedin_premium` is single-valued.
+   *
+   * STILL EXPORTED for the same reason as {@link TIER_NOT_ACTIVE}: deployments
+   * that predate the connect rework can still emit it, and dropping it early
+   * would turn a fixable refusal into `INTERNAL` on exactly those. Withdrawn
+   * in the first release after every deployment carries the new contract.
+   */
   "PREMIUM_CONFLICT",
   // A reconnect whose seat-derived scope differs from the account's recorded
   // scope was attempted with cookie auth; a cookie replay cannot change
@@ -101,12 +134,58 @@ var ERROR_CODES = [
   "SUBSCRIPTION_NOT_FOUND",
   "SEAT_NOT_FOUND",
   "SEAT_CANCELLED",
+  // ── Codes that used to collapse to INTERNAL ──────────────────────────────
+  //
+  // Every code below is returned by a `/v1` route, the `/v1` catch-all, or a
+  // shared handler one of them calls. Because this union did not carry them,
+  // the transport decoded each to `INTERNAL`: a refusal the caller could
+  // usually fix arrived looking like a server fault, with no `switch` arm
+  // possible and nothing but `retryLikelyToSucceed` left to branch on. They
+  // are grouped by what a caller does about them rather than by HTTP status.
+  // Routing. A path this API does not serve, which is also what a mistyped
+  // URL returns, so check the path shape before the ids.
+  "NOT_FOUND",
+  // The reaction you asked to remove is not on that post (422). Not a
+  // transport failure and not a bad id shape: re-read the post's reactions
+  // before retrying.
+  "REACTION_NOT_FOUND",
+  // Upstream failures on the connect and billing paths. All transient in the
+  // ordinary sense (502/503 from a dependency), so a retry is reasonable.
+  "SUBSTRATE_LINK_FAILED",
+  "SUBSTRATE_CAP_REACHED",
+  "BILLING_CHECKOUT_FAILED",
+  "BILLING_PORTAL_UNAVAILABLE",
+  // Tenant standing. The workspace's billing state forbids the operation
+  // (delinquent, disputed, linking switched off). The remedy is in billing,
+  // and none of these clears on retry.
+  "ACCOUNT_DISPUTED",
+  "ACCOUNT_LINKING_DISABLED",
+  "PERIOD_LOCKED",
+  // Seat and subscription state conflicts. The request is well formed and the
+  // target is in a state that refuses it, so read the state before resending.
+  "SEAT_NOT_EMPTY",
+  "SEAT_PROVISIONAL",
+  "SUBSCRIPTION_ALREADY_EXISTS",
+  "ALREADY_CANCELLED",
+  "CANCELLATION_ALREADY_EFFECTIVE",
+  "INVALID_CANCELLATION_SOURCE",
+  // Free-trial limits and the trial abuse gate. `TRIAL_EXPIRED` is the 402;
+  // the rest are 409/422 refusals on connect. All user_fixable, none
+  // retryable as sent.
+  "TRIAL_EXPIRED",
+  "TRIAL_SEAT_LIMIT",
+  "TRIAL_ACTIVE_SEAT_LIMIT",
+  "TRIAL_IDENTITY_ALREADY_USED",
+  "TRIAL_IDENTITY_UNRESOLVED",
+  // Admin-tenant refusal (400): an admin workspace has no Stripe billing, so
+  // the billing operations do not apply to it. Documented here because it is
+  // returned by `/v1` billing routes at nine sites; it was previously cited
+  // in this file as a code that never reaches a caller, which was wrong.
+  "ADMIN_BYPASS",
   // Generic
   "INTERNAL"
 ];
 var KNOWN_ERROR_CODES = new Set(ERROR_CODES);
-var REQUIRED_TIERS = ["core", "sn", "sales_nav", "recruiter"];
-var KNOWN_REQUIRED_TIERS = new Set(REQUIRED_TIERS);
 var CurviateError = class _CurviateError extends Error {
   constructor(init) {
     super(init.message);
@@ -116,7 +195,6 @@ var CurviateError = class _CurviateError extends Error {
     this.retryHint = init.retryHint ?? null;
     this.userFixable = init.userFixable;
     this.retryLikelyToSucceed = init.retryLikelyToSucceed;
-    this.requiredTier = init.requiredTier;
     this.retryAfterMs = init.retryAfterMs;
     this.budgetRow = init.budgetRow;
     this.retryAfterSeconds = init.retryAfterSeconds;
@@ -141,7 +219,6 @@ var CurviateError = class _CurviateError extends Error {
       retryLikelyToSucceed: this.retryLikelyToSucceed
     };
     if (this.httpStatus !== void 0) json.httpStatus = this.httpStatus;
-    if (this.requiredTier !== void 0) json.requiredTier = this.requiredTier;
     if (this.retryAfterMs !== void 0) json.retryAfterMs = this.retryAfterMs;
     if (this.budgetRow !== void 0) json.budgetRow = this.budgetRow;
     if (this.retryAfterSeconds !== void 0) json.retryAfterSeconds = this.retryAfterSeconds;
@@ -186,8 +263,7 @@ var RETRYABLE_CODES = /* @__PURE__ */ new Set([
   "PLATFORM_ERROR",
   "PLATFORM_RATE_LIMIT",
   "RATE_LIMIT_ACCOUNT",
-  "RATE_LIMIT_TENANT",
-  "RATE_LIMITED"
+  "RATE_LIMIT_TENANT"
   // BUDGET_EXHAUSTED is deliberately NOT here, even though it is a 429. It is
   // Curviate's own account-safety ceiling rather than a request-rate limit:
   // nothing reached LinkedIn, nothing was spent, and a monthly row's reset can
@@ -236,7 +312,6 @@ async function errorFromResponse(res) {
   } catch {
     env = void 0;
   }
-  const requiredTier = env?.required_tier && KNOWN_REQUIRED_TIERS.has(env.required_tier) ? env.required_tier : void 0;
   const safetyHint = toSafetyHint(env?.hint);
   const safetyReason = toSafetyReason(env?.reason);
   return new CurviateError({
@@ -246,7 +321,6 @@ async function errorFromResponse(res) {
     retryHint: toRetryHint(env?.retry_hint),
     userFixable: env?.user_fixable ?? false,
     retryLikelyToSucceed: env?.retry_likely_to_succeed ?? false,
-    ...requiredTier !== void 0 ? { requiredTier } : {},
     ...retryAfterMs !== void 0 ? { retryAfterMs } : {},
     ...typeof env?.row === "string" ? { budgetRow: env.row } : {},
     // `retry_after` is DELIBERATELY NOT folded into `retryAfterMs`. Everything
@@ -547,16 +621,31 @@ var AuthResource = class {
    * account) rather than connecting a brand-new one; it is absent on a normal
    * connect.
    *
-   * Connection scope (which LinkedIn products are enabled: classic, company,
-   * a premium tier) is **seat-derived**: there is no products input on this
-   * body, and the recorded scope is readable back as `requested_products` on
-   * the account (`accounts.list()` / `accounts.get()`). A reconnect that
-   * would change scope must use `auth_method: "credentials"`, since a cookie
-   * replay cannot change scope and throws `CurviateError(code:
-   * "REAUTH_REQUIRED")` instead. A seat resolving to both individual-Premium
-   * tiers at once throws `CurviateError(code: "PREMIUM_CONFLICT")` (LinkedIn
-   * permits only one per profile). Pin a managed proxy with the optional
-   * `country`/`ip`, or supply `proxy` to override it entirely.
+   * Connection scope (which LinkedIn products are enabled) is not something
+   * you enumerate and it is NOT derived from the seat: the connect asks for
+   * every product (classic, company, sales_navigator, recruiter) and LinkedIn
+   * activates whichever ones the account actually holds. The recorded scope is
+   * readable back as `requested_products` on the account
+   * (`accounts.list()` / `accounts.get()`), and it is what was ASKED for, not
+   * proof of attachment.
+   *
+   * `linkedin_premium` (`"sales_navigator"` | `"recruiter"`) is the one
+   * optional narrowing. A LinkedIn account can hold only one of the two
+   * premium surfaces, and when both are asked for Sales Navigator wins, so set
+   * it to `"recruiter"` for an account that holds both and needs the Recruiter
+   * surface. **It applies to this connection only and is never remembered**:
+   * a later connect or reconnect that omits it widens the scope back to every
+   * product, so state it on every call where Recruiter must win. There is no
+   * account-level premium preference to set once.
+   *
+   * A reconnect that would change scope must use `auth_method: "credentials"`,
+   * since a cookie replay cannot change scope and throws
+   * `CurviateError(code: "REAUTH_REQUIRED")` instead. Asking for a premium the
+   * LinkedIn account does not hold throws
+   * `CurviateError(code: "LINKEDIN_FEATURE_NOT_SUBSCRIBED")` (403); the remedy
+   * is to activate the subscription on LinkedIn or to point `linkedin_premium`
+   * at the premium the account really has. Pin a managed proxy with the
+   * optional `country`/`ip`, or supply `proxy` to override it entirely.
    */
   intent(body) {
     return this.ctx.request({
@@ -1598,6 +1687,10 @@ var InboxesResource = class {
    * const companyPage = (items ?? []).find((i) => i.kind === "company");
    * console.log(companyPage?.id, companyPage?.name, hint);
    * // companyPage?.id is what you pass to listChats(), e.g. "COMPANY_83734124_PRIMARY"
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   list(params) {
     return this.ctx.request({
@@ -1634,6 +1727,10 @@ var InboxesResource = class {
    *   or `"COMPANY_83734124_PRIMARY"`).
    * @param params - optional `limit` (1-25, default 20) and an opaque
    *   `cursor` for pagination.
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   listChats(inboxId, params) {
     return this.ctx.request({
@@ -1733,7 +1830,10 @@ var SalesNavigatorResource = class {
   /**
    * Search LinkedIn members using the full Sales Navigator filter set.
    * `POST /v1/{account_id}/sales-navigator/search/people`
-   * Requires tier `sn`. Returns `TIER_NOT_ACTIVE` (403) when the seat lacks it.
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchPeople(body, query) {
     return this.ctx.request({
@@ -1746,6 +1846,10 @@ var SalesNavigatorResource = class {
   /**
    * Search LinkedIn companies using the full Sales Navigator company filter set.
    * `POST /v1/{account_id}/sales-navigator/search/companies`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchCompanies(body, query) {
     return this.ctx.request({
@@ -1758,6 +1862,10 @@ var SalesNavigatorResource = class {
   /**
    * Resolve human-readable terms to opaque Sales Navigator filter IDs.
    * `GET /v1/{account_id}/sales-navigator/search/parameters`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getParameters(query) {
     return this.ctx.request({
@@ -1770,6 +1878,10 @@ var SalesNavigatorResource = class {
    * Start a new Sales Navigator chat. `attachments[]`, when supplied, carry
    * base64-encoded file bytes, always sent as JSON, never multipart.
    * `POST /v1/{account_id}/sales-navigator/chats`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   startChat(body) {
     return this.ctx.request({
@@ -1781,6 +1893,10 @@ var SalesNavigatorResource = class {
   /**
    * Retrieve a LinkedIn profile with Sales Navigator enrichment.
    * `GET /v1/{account_id}/sales-navigator/profiles/{identifier}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getProfile(identifier, query) {
     return this.ctx.request({
@@ -1793,6 +1909,10 @@ var SalesNavigatorResource = class {
   /**
    * List the saved-account (company) lists on the operator's Sales Navigator seat.
    * `GET /v1/{account_id}/sales-navigator/account-lists`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   accountLists(query) {
     return this.ctx.request({
@@ -1804,6 +1924,10 @@ var SalesNavigatorResource = class {
   /**
    * List the saved-lead (member) lists on the operator's Sales Navigator seat.
    * `GET /v1/{account_id}/sales-navigator/lead-lists`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   leadLists(query) {
     return this.ctx.request({
@@ -1816,6 +1940,10 @@ var SalesNavigatorResource = class {
    * Browse the saved accounts (companies) in one account list. Pass optional
    * `persona` / `filter` / `sort_by` / `sort_order` filters in the body.
    * `POST /v1/{account_id}/sales-navigator/account-lists/{list_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   browseAccountList(listId, body, query) {
     return this.ctx.request({
@@ -1829,6 +1957,10 @@ var SalesNavigatorResource = class {
    * Browse the saved leads (members) in one lead list. Pass optional
    * `spotlight` / `sort_by` / `sort_order` filters in the body.
    * `POST /v1/{account_id}/sales-navigator/lead-lists/{list_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   browseLeadList(listId, body, query) {
     return this.ctx.request({
@@ -1845,6 +1977,10 @@ var SalesNavigatorResource = class {
    *
    * No `saved` boolean is invented; a `2xx` response body is the success
    * signal (the substrate returns no success flag).
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   saveAccount(input) {
     const { list_id, ...body } = input;
@@ -1858,6 +1994,10 @@ var SalesNavigatorResource = class {
    * Save a Sales Navigator member into a lead list. Body is just `{user_id}`;
    * `account_id` lives in the path, not the body.
    * `POST /v1/{account_id}/sales-navigator/lead-lists/{list_id}/save`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   saveLead(input) {
     const { list_id, ...body } = input;
@@ -1872,6 +2012,10 @@ var SalesNavigatorResource = class {
    * `POST /v1/{account_id}/sales-navigator/search`
    * `url` is the only accepted body field. Response items are polymorphic,
    * each discriminated individually by its own `object`.
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchFromUrl(body, query) {
     return this.ctx.request({
@@ -1908,6 +2052,10 @@ var RecruiterResource = class {
    * target's public identifier, or a member id. Request specific profile
    * sections via `with_sections` (repeatable query param).
    * `GET /v1/{account_id}/recruiter/profiles/{user_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getProfile(identifier, params) {
     return this.ctx.request({
@@ -1920,6 +2068,10 @@ var RecruiterResource = class {
    * Start a Recruiter chat (InMail). JSON-only, `subject` and `signature`
    * are REQUIRED; optional attachments ride the body as base64-encoded
    * objects (no multipart). `POST /v1/{account_id}/recruiter/chats`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   startChat(body) {
     return this.ctx.request({
@@ -1931,6 +2083,10 @@ var RecruiterResource = class {
   /**
    * Search LinkedIn members using Recruiter filters. `limit`/`cursor` stay
    * TOP-LEVEL query params. `POST /v1/{account_id}/recruiter/search/people`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchPeople(body, params) {
     return this.ctx.request({
@@ -1944,6 +2100,10 @@ var RecruiterResource = class {
    * Resolve human-readable terms to opaque Recruiter filter ids. POST (was
    * GET): the body is a `source`-discriminated oneOf, `APPLICANTS`/`PIPELINE`
    * require `project_id`. `POST /v1/{account_id}/recruiter/search/parameters`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchParameters(body, params) {
     return this.ctx.request({
@@ -1958,6 +2118,10 @@ var RecruiterResource = class {
    * `RECRUITER_SEARCH` talent-pool channel) is REQUIRED. `limit`/`cursor` stay
    * TOP-LEVEL query params.
    * `POST /v1/{account_id}/recruiter/projects/{project_id}/talent-pool/search`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchTalentPool(projectId, body, params) {
     return this.ctx.request({
@@ -1972,6 +2136,10 @@ var RecruiterResource = class {
    * nothing else in the body. The response is a 3-way oneOf (people-search,
    * job-applicant list, or pipeline-candidate list) keyed by the URL kind.
    * `POST /v1/{account_id}/recruiter/search`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   searchFromUrl(body, params) {
     return this.ctx.request({
@@ -1984,6 +2152,10 @@ var RecruiterResource = class {
   /**
    * List Recruiter hiring projects visible to the account.
    * `GET /v1/{account_id}/recruiter/projects`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   listProjects(params) {
     return this.ctx.request({
@@ -1995,6 +2167,10 @@ var RecruiterResource = class {
   /**
    * Get a single Recruiter hiring project (owner, metadata, talent_pool,
    * pipeline). `GET /v1/{account_id}/recruiter/projects/{project_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getProject(projectId) {
     return this.ctx.request({
@@ -2006,6 +2182,10 @@ var RecruiterResource = class {
    * Edit a Recruiter project's config: all fields optional; omitted fields
    * are left unchanged. Returns a thin acknowledgement only.
    * `PATCH /v1/{account_id}/recruiter/projects/{project_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   updateProject(projectId, body) {
     return this.ctx.request({
@@ -2019,6 +2199,10 @@ var RecruiterResource = class {
    * an all-optional filter set, no state mutates). `limit`/`cursor` stay
    * TOP-LEVEL query params.
    * `POST /v1/{account_id}/recruiter/projects/{project_id}/pipeline`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   listPipeline(projectId, body = {}, params) {
     return this.ctx.request({
@@ -2032,6 +2216,10 @@ var RecruiterResource = class {
    * Get the single job posting attached to a Recruiter project (the surface
    * returns one posting, not a list; a project with no attached job 404s).
    * `GET /v1/{account_id}/recruiter/projects/{project_id}/jobs`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getProjectJob(projectId) {
     return this.ctx.request({
@@ -2043,6 +2231,10 @@ var RecruiterResource = class {
    * Create a job-posting DRAFT attached to an EXISTING project, `project_name`
    * is not accepted (the project comes from the path). Never publishes, never
    * spends money. `POST /v1/{account_id}/recruiter/projects/{project_id}/jobs`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   createProjectJob(projectId, body) {
     return this.ctx.request({
@@ -2055,6 +2247,10 @@ var RecruiterResource = class {
    * Get pricing to publish a project's job posting; price a publish before
    * committing any money.
    * `GET /v1/{account_id}/recruiter/projects/{project_id}/jobs/{job_id}/budget`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getProjectJobBudget(projectId, jobId) {
     return this.ctx.request({
@@ -2066,6 +2262,10 @@ var RecruiterResource = class {
    * Create a job-posting DRAFT together with a brand-new hiring project,
    * `project_name` is REQUIRED; `description` must be >= 200 characters. Never
    * publishes, never spends money. `POST /v1/{account_id}/recruiter/jobs`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   createJob(body) {
     return this.ctx.request({
@@ -2077,6 +2277,10 @@ var RecruiterResource = class {
   /**
    * List Recruiter job postings. `limit`/`cursor` stay TOP-LEVEL query params.
    * `GET /v1/{account_id}/recruiter/jobs`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   listJobs(params) {
     return this.ctx.request({
@@ -2095,6 +2299,10 @@ var RecruiterResource = class {
    * client-side; the wire request always carries the numeric id. Throws
    * `CurviateError({ code: 'INVALID_REQUEST' })` synchronously if neither
    * form can be recognized.
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getJob(jobIdOrUrl) {
     const jobId = resolveJobId(jobIdOrUrl);
@@ -2108,6 +2316,10 @@ var RecruiterResource = class {
    * change. MONEY WARNING: editing an already-published (LISTED) posting
    * mutates a live, money-spending listing.
    * `PATCH /v1/{account_id}/recruiter/projects/{project_id}/jobs/{job_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   updateProjectJob(projectId, jobId, body) {
     return this.ctx.request({
@@ -2123,6 +2335,10 @@ var RecruiterResource = class {
    * the connected account's LinkedIn payment method; supplying `budget` IS the
    * explicit opt-in).
    * `POST /v1/{account_id}/recruiter/projects/{project_id}/jobs/{job_id}/publish`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   publishJob(projectId, jobId, body) {
     return this.ctx.request({
@@ -2136,6 +2352,10 @@ var RecruiterResource = class {
    * (bodyless). Closing an already-published (LISTED) posting cannot be
    * undone; there is no re-open operation.
    * `POST /v1/{account_id}/recruiter/projects/{project_id}/jobs/{job_id}/close`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   closeJob(projectId, jobId) {
     return this.ctx.request({
@@ -2147,6 +2367,10 @@ var RecruiterResource = class {
    * Save a candidate (or user profile) to a project's pipeline at the given
    * stage, the sole surviving pipeline write.
    * `POST /v1/{account_id}/recruiter/projects/{project_id}/pipeline/candidate/save`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   saveCandidate(projectId, body) {
     return this.ctx.request({
@@ -2160,6 +2384,10 @@ var RecruiterResource = class {
    * filters, no state mutates). `channel_id` (a `JOB_POSTING` talent-pool
    * channel) is REQUIRED. `limit`/`cursor` stay TOP-LEVEL query params.
    * `POST /v1/{account_id}/recruiter/projects/{project_id}/talent-pool/applicants`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   listApplicants(projectId, body, params) {
     return this.ctx.request({
@@ -2172,6 +2400,10 @@ var RecruiterResource = class {
   /**
    * Get full detail for one talent-pool applicant (profile guaranteed full,
    * includes PII). `GET /v1/{account_id}/recruiter/projects/{project_id}/talent-pool/applicants/{applicant_id}`
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   getApplicant(projectId, applicantId) {
     return this.ctx.request({
@@ -2183,6 +2415,10 @@ var RecruiterResource = class {
    * Download a talent-pool applicant's résumé as raw binary.
    * `GET /v1/{account_id}/recruiter/projects/{project_id}/talent-pool/applicants/{applicant_id}/resume`
    * Returns `ArrayBuffer`; the SDK does not cache or store it.
+   *
+   * @beta Beta operation. See the namespace note above: while beta-gated it
+   * refuses `BETA_NOT_ENABLED` (403) until a human enables beta in Settings,
+   * or the request carries the `X-Curviate-Beta` header.
    */
   downloadResume(projectId, applicantId) {
     return this.ctx.request({
@@ -2469,6 +2705,11 @@ var CompaniesResource = class {
    * never stored. Beta: single-page listing and termination are verified;
    * deep pagination (many pages / large cursor round-trips) is provisional
    * until validated against a busier inbox.
+   *
+   * @beta Beta operation. While beta-gated it refuses `BETA_NOT_ENABLED`
+   * (403) until a human enables beta in Settings, or the request carries the
+   * `X-Curviate-Beta` header. Sibling methods on this namespace are stable;
+   * the badge is per operation.
    */
   chats(identifier, params) {
     return this.ctx.request({
@@ -2523,6 +2764,11 @@ var CompaniesResource = class {
    * and message content), a `topic` card, or `unread`-only; the three are
    * mutually exclusive and enforced server-side. The connected account must
    * administer the page. Beta: see `chats()`.
+   *
+   * @beta Beta operation. While beta-gated it refuses `BETA_NOT_ENABLED`
+   * (403) until a human enables beta in Settings, or the request carries the
+   * `X-Curviate-Beta` header. Sibling methods on this namespace are stable;
+   * the badge is per operation.
    */
   searchChats(identifier, params) {
     return this.ctx.request({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curviate/sdk",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "private": false,
   "description": "TypeScript SDK for the Curviate API.",
   "license": "MIT",