arcmira 0.2.0 → 0.3.0

package/README.md

@@ -22,6 +22,26 @@ npx arcmira setup             # apply, then sign in once per agent
 
 Get a key at [arcmira.com/docs/authentication](https://arcmira.com/docs/authentication) and set `ARCMIRA_API_KEY`, or pass `apiKey` to the client.
 
+## Premium quickstart
+
+```ts
+import { ArcmiraClient } from "arcmira";
+const arcmira = new ArcmiraClient();
+const transcript = await arcmira.transcripts.prepareAndWait({ video_id: "dQw4w9WgXcQ" });
+for (const line of transcript.lines ?? []) console.log(line.speaker, line.text);
+```
+
+`prepareAndWait({ video_id, maxOnDemandCents = 0, timeoutSeconds = 300 })` reads the Premium transcript and returns it. When your account does not own it yet, the call posts `{ video_id }` to `/v1/transcriptions` once, polls the job at the pace the API sets with `Retry-After` and `next_poll_seconds`, and reads the finished transcript. The default spends included credits only and sends no `Idempotency-Key`. Preparation buys the whole video, even if you later read a window.
+
+Errors you can handle:
+
+- `PreparationTimeoutError` when the job outlasts `timeoutSeconds`. It carries `job`, and the job keeps running.
+- `PreparationFailedError` when the job fails or is refunded. It carries `job`.
+- `PremiumUnavailableError` when the plan has no Premium. The read returned captions, which are never returned as Premium.
+- `ArcmiraError` subclasses for any API refusal, such as `quota_exceeded`, with the API's error object in `body`.
+
+To spend money, pass a cents ceiling you have approved: `prepareAndWait({ video_id, maxOnDemandCents: 25 })`. The call then sends the quoted `max_rows` and one generated `Idempotency-Key`, which the SDK's retries reuse.
+
 ## Quickstart
 
 ```ts
@@ -62,12 +82,15 @@ try {
 }
 ```
 
-Order a Premium transcript and poll it (paid plans; pass your own idempotency key so a retry cannot order twice):
+To prepare Premium without waiting, read it, post the purchase, and poll the job yourself. GET never buys, and each state is typed. Every purchase answers one `TranscriptJob`. Without an `Idempotency-Key`, a purchase already open or owned for the video comes back with `existing: true`. A positive `max_on_demand_cents` requires both `Idempotency-Key` and `max_rows`.
 
 ```ts
-const order = await client.transcripts.request({ videoId: "dQw4w9WgXcQ", "Idempotency-Key": "order-dQw4w9WgXcQ-1" });
-const state = await client.transcripts.status({ id: order.request.id! });
-console.log(state.status, state.nextPollSeconds);
+const read = await client.transcripts.get({ video_id: "dQw4w9WgXcQ", quality: "premium" });
+if (read.state === "preparation_required") {
+    const { job } = await client.transcripts.request({ video_id: read.video_id });
+    console.log(job.state, job.next_poll_seconds, job.status_url);
+}
+for await (const job of await client.transcripts.listRequests({ limit: 10 })) console.log(job.id, job.state);
 ```
 
 Every method is listed with its request and response types in [reference.md](./reference.md). The same operations, with `curl` samples, are in the [API reference](https://arcmira.com/docs/api-reference).
@@ -138,7 +161,8 @@ Data commands (they mirror the MCP tools)
   arcmira recommendations <id|name>   who recommends an entity on air, paid or organic
   arcmira episodes <channel>          newest indexed videos of a channel
   arcmira transcripts get <video>     full transcript of one YouTube video
-  arcmira transcripts request <video> order a Premium transcript (paid plans; sends an Idempotency-Key)
+  arcmira transcripts quote <video>   free whole-video quote
+  arcmira transcripts request <video> --max-rows N --idempotency-key KEY [--max-on-demand-cents N]
   arcmira transcripts status <id>     state of a transcript request, with the next poll time
   arcmira occurrences --channel ...   ranked counts of the entities a set of channels or videos mention
   arcmira status [channel]            your plan, or a channel's coverage
@@ -170,15 +194,17 @@ Also: arcmira help [command], --help, --version
 
 Commands that take an `ent_` or `UC` id also take a name or `@handle`; the CLI resolves it first (one extra call to `GET /v1/entities/resolve`) and says what it picked on stderr. A suggested pick is used and stated as an assumption with its reason. An ambiguous name exits 2 and lists the options with their ids.
 
-`arcmira transcripts request` sends a new `Idempotency-Key` (a UUID) with each order and prints it on stderr; with `--json` stderr stays reserved for the error, so scripts pass their own key. To retry an order whose answer you did not see, pass the same key with `--idempotency-key`; the API returns the first answer and charges nothing more. A request for a video already in flight returns that request.
+`arcmira transcripts get <video> --quality premium --wait` reads Premium, prepares it from included credits when your account does not own it yet (one keyless `POST /v1/transcriptions`, no money moves), waits for the job, and prints the transcript. `--timeout S` bounds the wait (default 300). Without `--wait`, a read never buys: when Premium needs preparing, the CLI exits 3 and prints the `--wait` command to run on stderr, and a job still running exits 4. With `--json` the API body is still printed on stdout, so `arcmira transcripts get X --quality premium --json | jq` fails on the exit code under `set -o pipefail`.
+
+`arcmira transcripts request` posts the same keyless purchase without waiting and prints the job. To spend on-demand money, pass the cents you approve with `--max-on-demand-cents`, plus `--max-rows` and a previously saved `--idempotency-key`; retry an unknown response with the same key and identical input. Whole-video pricing applies even when you later read a small window.
 
-`arcmira api` follows `gh api`: `-f` adds a string parameter and `-F` a typed one (`true`, `false`, `null`, numbers, `@file`, `key[]=value`). They go to the query string on GET and DELETE, and into a JSON body otherwise. Every POST carries an automatic `Idempotency-Key` (a UUID, shown with `--verbose`; pass `-H 'Idempotency-Key: ...'` to set your own), so a retried write does not run twice. The path may drop the `/v1` prefix.
+`arcmira api` follows `gh api`: `-f` adds a string parameter and `-F` a typed one (`true`, `false`, `null`, numbers, `@file`, `key[]=value`). They go to the query string on GET and DELETE, and into a JSON body otherwise. For `POST /v1/transcriptions`, pass your saved key with `-H 'Idempotency-Key: ...'`. Other POST requests generate a key when none is supplied; `--verbose` shows it. Reuse the same key and input to retry a write. The path may drop the `/v1` prefix.
 
 - Key: `--key`, then `ARCMIRA_API_KEY`, then the key `arcmira login` saved in `~/.config/arcmira/config.json` (mode 0600; `XDG_CONFIG_HOME` is honored). `arcmira login --key arc_sk_...` saves a key you already have; `arcmira logout` deletes it.
 - Output: data on stdout, notes and errors on stderr, no colour. `--json` prints the API response unchanged on stdout; on failure it prints `{"error":{"type","code","message","request_id",...}}` on stderr, the API's own error body or a `usage_error` in the same shape.
 - Errors: every API error names its `request_id` (quote it to support). A 401 adds `try: arcmira login`.
 - Paging: `mentions` and `recommendations` take `--cursor`; the next page's command is printed on stderr, and `next_cursor` is in `--json`. `arcmira api --paginate` follows every page.
-- Exit codes: 0 ok, 1 an API or network error (the message names the code and any unlock link), 2 a usage error (bad input, no key, an unresolved name, a command or flag not available yet). Input is checked before any request.
+- Exit codes: 0 ok, 1 an API or network error (the message names the code and any unlock link), 2 a usage error (bad input, no key, an unresolved name, a command or flag not available yet), 3 Premium needs preparing (stderr names the `--wait` command), 4 Premium is still pending (the job keeps running; run the same command again). Input is checked before any request.
 - Reserved flags: `--dry-run`, `--force`, `-y`/`--yes`, `--profile` and `--jq` exit 2 in this version outside `arcmira setup`; their names are held for write commands to come.
 - Requests carry `User-Agent: arcmira-cli/<version>`. The SDK used on its own sends `arcmira/<version>`.
 - Telemetry: none. The CLI sends only the API requests you ask for, plus a docs search when you run `arcmira docs <query>`.
@@ -197,8 +223,27 @@ Commands that take an `ent_` or `UC` id also take a name or `@handle`; the CLI r
 
 ## Development
 
-`src/` is generated from the Arcmira OpenAPI document by [Fern](https://github.com/fern-api/fern); do not edit it by hand, a regeneration overwrites it. `cli/`, `tests/` and this file are hand-written. `npm test` builds and runs the tests against a local fake of the API (`tests/fake-v1.mjs`, bodies in `tests/fixtures/v1.json`).
+`src/` is generated from the Arcmira OpenAPI document by [Fern](https://github.com/fern-api/fern); do not edit it by hand, a regeneration overwrites it. The one exception is `src/wrapper/`, which holds `transcripts.prepareAndWait`; the installer keeps it and points `src/index.ts` at its `ArcmiraClient`. `cli/`, `tests/` and this file are hand-written. `npm test` builds and runs the tests against a local fake of the API (`tests/fake-v1.mjs`, bodies in `tests/fixtures/v1.json`).
 
 ## License
 
 Apache-2.0. See [LICENSE](./LICENSE).
+
+## Regenerate the SDK
+
+Run `npm run generate -- <path to arcmira-v1.json>` with Node 22 or newer, Python 3, Docker, and Fern access for the `arcmira` organization. It vendors the spec into `fern/openapi.json` (omit the path to reuse the vendored copy), pins Fern CLI 5.131.1 and TypeScript generator 3.96.0, disables CLI version redirection and telemetry, and regenerates `src/`, `reference.md` and `cli/operations.ts`.
+
+The overlay combines success schemas into a `state` union, preserves existing method names, and discovers cursor collections from their schemas. Unknown or ambiguous collections fail generation. An exact checked patch keeps request timer cleanup in `finally` until the pinned generator includes the fix. Generated source is never edited by hand.
+
+Run `npm test` for the SDK and CLI tests, and `npm run test:types` for the consumer type contract. Tests use local HTTP fixtures and do not purchase transcripts.
+
+## Migrate from 0.2
+
+`transcripts.get` returns `TranscriptResult`. Narrow on `state` before accessing transcript lines. Use `.withRawResponse()` for HTTP status and headers. `transcripts.request` takes `video_id` and answers `{ job, existing }`. `channels.videos.list` and `transcripts.listRequests` return pages: iterate them with `for await`, or read `page.response` for the list body. See [CHANGELOG.md](./CHANGELOG.md).
+
+```ts
+const { data, rawResponse } = await client.transcripts.get({ video_id: "dQw4w9WgXcQ", quality: "premium" }).withRawResponse();
+if (data.state === "ready") console.log(data.lines);
+else if (data.state === "pending") console.log(data.job.status_url, data.job.next_poll_seconds, rawResponse.status);
+else console.log(data.quote, data.action);
+```

package/dist/cjs/BaseClient.js

@@ -43,8 +43,8 @@ function normalizeClientOptions(options) {
     const headers = (0, headers_js_1.mergeHeaders)({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "arcmira",
-        "X-Fern-SDK-Version": "0.2.0",
-        "User-Agent": "arcmira/0.2.0",
+        "X-Fern-SDK-Version": "0.3.0",
+        "User-Agent": "arcmira/0.3.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);

package/dist/cjs/api/errors/PreconditionFailedError.d.ts

@@ -2,6 +2,6 @@ import type * as core from "../../core/index.js";
 import * as errors from "../../errors/index.js";
 import type * as Arcmira from "../index.js";
 export declare class PreconditionFailedError extends errors.ArcmiraError {
-    readonly body: Arcmira.CorrectionSeqMismatchResponse;
-    constructor(body: Arcmira.CorrectionSeqMismatchResponse, rawResponse?: core.RawResponse);
+    readonly body: Arcmira.Error_;
+    constructor(body: Arcmira.Error_, rawResponse?: core.RawResponse);
 }

package/dist/cjs/api/errors/index.d.ts

@@ -8,4 +8,3 @@ export * from "./PreconditionFailedError.js";
 export * from "./ServiceUnavailableError.js";
 export * from "./TooManyRequestsError.js";
 export * from "./UnauthorizedError.js";
-export * from "./UnprocessableEntityError.js";

package/dist/cjs/api/errors/index.js

@@ -24,4 +24,3 @@ __exportStar(require("./PreconditionFailedError.js"), exports);
 __exportStar(require("./ServiceUnavailableError.js"), exports);
 __exportStar(require("./TooManyRequestsError.js"), exports);
 __exportStar(require("./UnauthorizedError.js"), exports);
-__exportStar(require("./UnprocessableEntityError.js"), exports);

package/dist/cjs/api/resources/channels/resources/guests/client/Client.d.ts

@@ -11,7 +11,7 @@ export declare class GuestsClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<GuestsClient.Options>;
     constructor(options?: GuestsClient.Options);
     /**
-     * People who appeared as guests on the channel, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * People who appeared as guests on the channel, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.ListGuestsRequest} request
      * @param {GuestsClient.RequestOptions} requestOptions - Request-specific configuration.

package/dist/cjs/api/resources/channels/resources/guests/client/Client.js

@@ -56,7 +56,7 @@ class GuestsClient {
         this._options = (0, BaseClient_js_1.normalizeClientOptionsWithAuth)(options);
     }
     /**
-     * People who appeared as guests on the channel, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * People who appeared as guests on the channel, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.ListGuestsRequest} request
      * @param {GuestsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -80,7 +80,7 @@ class GuestsClient {
         return __awaiter(this, void 0, void 0, function* () {
             const list = core.HttpResponsePromise.interceptFunction((request) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-                const { slug, limit, cursor, q, field, sort, order } = request;
+                const { slug, limit, cursor, q, field, sort, order, mode, is_appearance: isAppearance } = request;
                 const _queryParams = {
                     limit,
                     cursor,
@@ -88,6 +88,8 @@ class GuestsClient {
                     field,
                     sort,
                     order: order != null ? order : undefined,
+                    mode: mode != null ? mode : undefined,
+                    is_appearance: isAppearance != null ? isAppearance : undefined,
                 };
                 const _authRequest = yield this._options.authProvider.getAuthRequest();
                 const _headers = (0, headers_js_1.mergeHeaders)(_authRequest.headers, (_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);

package/dist/cjs/api/resources/channels/resources/guests/client/requests/ListGuestsRequest.d.ts

@@ -9,7 +9,7 @@ export interface ListGuestsRequest {
     /** The entity slug: the last segment of its arcmira.com page URL, as EntityRef.slug carries it. */
     slug: string;
     limit?: number;
-    /** Opaque cursor from a previous page's next_cursor. */
+    /** Signed continuation from next_cursor. Bound to route, filters, caller and visibility; invalid or old tokens return invalid_cursor. Person appearance publication pages use a media-id insertion fence; aggregate sorts remain live. */
     cursor?: string;
     /** Substring filter over the row's text columns (e.g. video title, channel name, description). */
     q?: string;
@@ -19,4 +19,8 @@ export interface ListGuestsRequest {
     sort?: string;
     /** Sort direction. Default desc. */
     order?: Arcmira.channels.ListGuestsRequestOrder;
+    /** Person relationship lens: guest appearances or inbound mentions. */
+    mode?: Arcmira.channels.ListGuestsRequestMode;
+    /** For person appearances, true lists guest episodes and false lists inbound mentions. */
+    is_appearance?: Arcmira.channels.ListGuestsRequestIsAppearance;
 }

package/dist/cjs/api/resources/channels/resources/guests/types/ListGuestsRequestIsAppearance.d.ts

@@ -0,0 +1,8 @@
+/** For person appearances, true lists guest episodes and false lists inbound mentions. */
+export declare const ListGuestsRequestIsAppearance: {
+    readonly Zero: "0";
+    readonly One: "1";
+    readonly True: "true";
+    readonly False: "false";
+};
+export type ListGuestsRequestIsAppearance = (typeof ListGuestsRequestIsAppearance)[keyof typeof ListGuestsRequestIsAppearance];

package/dist/cjs/api/resources/channels/resources/guests/types/ListGuestsRequestIsAppearance.js

@@ -0,0 +1,11 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListGuestsRequestIsAppearance = void 0;
+/** For person appearances, true lists guest episodes and false lists inbound mentions. */
+exports.ListGuestsRequestIsAppearance = {
+    Zero: "0",
+    One: "1",
+    True: "true",
+    False: "false",
+};

package/dist/cjs/api/resources/channels/resources/guests/types/ListGuestsRequestMode.d.ts

@@ -0,0 +1,6 @@
+/** Person relationship lens: guest appearances or inbound mentions. */
+export declare const ListGuestsRequestMode: {
+    readonly Appearances: "appearances";
+    readonly Mentions: "mentions";
+};
+export type ListGuestsRequestMode = (typeof ListGuestsRequestMode)[keyof typeof ListGuestsRequestMode];

package/dist/cjs/api/resources/channels/resources/guests/types/ListGuestsRequestMode.js

@@ -0,0 +1,9 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListGuestsRequestMode = void 0;
+/** Person relationship lens: guest appearances or inbound mentions. */
+exports.ListGuestsRequestMode = {
+    Appearances: "appearances",
+    Mentions: "mentions",
+};

package/dist/cjs/api/resources/channels/resources/guests/types/index.d.ts

@@ -1 +1,3 @@
+export * from "./ListGuestsRequestIsAppearance.js";
+export * from "./ListGuestsRequestMode.js";
 export * from "./ListGuestsRequestOrder.js";

package/dist/cjs/api/resources/channels/resources/guests/types/index.js

@@ -14,4 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ListGuestsRequestIsAppearance.js"), exports);
+__exportStar(require("./ListGuestsRequestMode.js"), exports);
 __exportStar(require("./ListGuestsRequestOrder.js"), exports);

package/dist/cjs/api/resources/channels/resources/related/client/Client.d.ts

@@ -11,7 +11,7 @@ export declare class RelatedClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<RelatedClient.Options>;
     constructor(options?: RelatedClient.Options);
     /**
-     * The topics that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The topics that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.TopicsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -33,7 +33,7 @@ export declare class RelatedClient {
      */
     topics(request: Arcmira.channels.TopicsRelatedRequest, requestOptions?: RelatedClient.RequestOptions): Promise<core.Page<Arcmira.EntityTopicListResponse.Items.Item, Arcmira.EntityTopicListResponse>>;
     /**
-     * The people that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The people that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.PeopleRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -55,7 +55,7 @@ export declare class RelatedClient {
      */
     people(request: Arcmira.channels.PeopleRelatedRequest, requestOptions?: RelatedClient.RequestOptions): Promise<core.Page<Arcmira.EntityPeopleListResponse.Items.Item, Arcmira.EntityPeopleListResponse>>;
     /**
-     * The organizations that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The organizations that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.OrganizationsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -77,7 +77,7 @@ export declare class RelatedClient {
      */
     organizations(request: Arcmira.channels.OrganizationsRelatedRequest, requestOptions?: RelatedClient.RequestOptions): Promise<core.Page<Arcmira.EntityOrganizationListResponse.Items.Item, Arcmira.EntityOrganizationListResponse>>;
     /**
-     * The products that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The products that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.ProductsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -99,7 +99,7 @@ export declare class RelatedClient {
      */
     products(request: Arcmira.channels.ProductsRelatedRequest, requestOptions?: RelatedClient.RequestOptions): Promise<core.Page<Arcmira.EntityProductListResponse.Items.Item, Arcmira.EntityProductListResponse>>;
     /**
-     * The channels that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The channels that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.ChannelsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.

package/dist/cjs/api/resources/channels/resources/related/client/Client.js

@@ -56,7 +56,7 @@ class RelatedClient {
         this._options = (0, BaseClient_js_1.normalizeClientOptionsWithAuth)(options);
     }
     /**
-     * The topics that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The topics that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.TopicsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -80,7 +80,7 @@ class RelatedClient {
         return __awaiter(this, void 0, void 0, function* () {
             const list = core.HttpResponsePromise.interceptFunction((request) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-                const { slug, limit, cursor, q, field, sort, order } = request;
+                const { slug, limit, cursor, q, field, sort, order, mode, is_appearance: isAppearance } = request;
                 const _queryParams = {
                     limit,
                     cursor,
@@ -88,6 +88,8 @@ class RelatedClient {
                     field,
                     sort,
                     order: order != null ? order : undefined,
+                    mode: mode != null ? mode : undefined,
+                    is_appearance: isAppearance != null ? isAppearance : undefined,
                 };
                 const _authRequest = yield this._options.authProvider.getAuthRequest();
                 const _headers = (0, headers_js_1.mergeHeaders)(_authRequest.headers, (_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
@@ -152,7 +154,7 @@ class RelatedClient {
         });
     }
     /**
-     * The people that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The people that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.PeopleRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -176,7 +178,7 @@ class RelatedClient {
         return __awaiter(this, void 0, void 0, function* () {
             const list = core.HttpResponsePromise.interceptFunction((request) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-                const { slug, limit, cursor, q, field, sort, order } = request;
+                const { slug, limit, cursor, q, field, sort, order, mode, is_appearance: isAppearance } = request;
                 const _queryParams = {
                     limit,
                     cursor,
@@ -184,6 +186,8 @@ class RelatedClient {
                     field,
                     sort,
                     order: order != null ? order : undefined,
+                    mode: mode != null ? mode : undefined,
+                    is_appearance: isAppearance != null ? isAppearance : undefined,
                 };
                 const _authRequest = yield this._options.authProvider.getAuthRequest();
                 const _headers = (0, headers_js_1.mergeHeaders)(_authRequest.headers, (_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
@@ -248,7 +252,7 @@ class RelatedClient {
         });
     }
     /**
-     * The organizations that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The organizations that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.OrganizationsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -272,7 +276,7 @@ class RelatedClient {
         return __awaiter(this, void 0, void 0, function* () {
             const list = core.HttpResponsePromise.interceptFunction((request) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-                const { slug, limit, cursor, q, field, sort, order } = request;
+                const { slug, limit, cursor, q, field, sort, order, mode, is_appearance: isAppearance } = request;
                 const _queryParams = {
                     limit,
                     cursor,
@@ -280,6 +284,8 @@ class RelatedClient {
                     field,
                     sort,
                     order: order != null ? order : undefined,
+                    mode: mode != null ? mode : undefined,
+                    is_appearance: isAppearance != null ? isAppearance : undefined,
                 };
                 const _authRequest = yield this._options.authProvider.getAuthRequest();
                 const _headers = (0, headers_js_1.mergeHeaders)(_authRequest.headers, (_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
@@ -344,7 +350,7 @@ class RelatedClient {
         });
     }
     /**
-     * The products that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The products that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.ProductsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -368,7 +374,7 @@ class RelatedClient {
         return __awaiter(this, void 0, void 0, function* () {
             const list = core.HttpResponsePromise.interceptFunction((request) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-                const { slug, limit, cursor, q, field, sort, order } = request;
+                const { slug, limit, cursor, q, field, sort, order, mode, is_appearance: isAppearance } = request;
                 const _queryParams = {
                     limit,
                     cursor,
@@ -376,6 +382,8 @@ class RelatedClient {
                     field,
                     sort,
                     order: order != null ? order : undefined,
+                    mode: mode != null ? mode : undefined,
+                    is_appearance: isAppearance != null ? isAppearance : undefined,
                 };
                 const _authRequest = yield this._options.authProvider.getAuthRequest();
                 const _headers = (0, headers_js_1.mergeHeaders)(_authRequest.headers, (_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);
@@ -440,7 +448,7 @@ class RelatedClient {
         });
     }
     /**
-     * The channels that co-occur with this channel in indexed media, with q/field/sort/order filtering. Cursor-paginated: rows are in items, and next_cursor (null on the last page) feeds the cursor parameter for the next page. total, offset, limit and hasMore mirror the web shape.
+     * The channels that co-occur with this channel in indexed media, with q/field/sort/order filtering. Signed cursor pagination: rows are in items, and next_cursor (null on the last page) feeds cursor. A token binds route, filters, caller and visibility; malformed or old tokens return invalid_cursor. Aggregate and display lists are live: changed ranks or deleted rows may shift later pages. total counts every matching row and limit is the page size applied.
      *
      * @param {Arcmira.channels.ChannelsRelatedRequest} request
      * @param {RelatedClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -464,7 +472,7 @@ class RelatedClient {
         return __awaiter(this, void 0, void 0, function* () {
             const list = core.HttpResponsePromise.interceptFunction((request) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-                const { slug, limit, cursor, q, field, sort, order } = request;
+                const { slug, limit, cursor, q, field, sort, order, mode, is_appearance: isAppearance } = request;
                 const _queryParams = {
                     limit,
                     cursor,
@@ -472,6 +480,8 @@ class RelatedClient {
                     field,
                     sort,
                     order: order != null ? order : undefined,
+                    mode: mode != null ? mode : undefined,
+                    is_appearance: isAppearance != null ? isAppearance : undefined,
                 };
                 const _authRequest = yield this._options.authProvider.getAuthRequest();
                 const _headers = (0, headers_js_1.mergeHeaders)(_authRequest.headers, (_a = this._options) === null || _a === void 0 ? void 0 : _a.headers, requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.headers);

package/dist/cjs/api/resources/channels/resources/related/client/requests/ChannelsRelatedRequest.d.ts

@@ -9,7 +9,7 @@ export interface ChannelsRelatedRequest {
     /** The entity slug: the last segment of its arcmira.com page URL, as EntityRef.slug carries it. */
     slug: string;
     limit?: number;
-    /** Opaque cursor from a previous page's next_cursor. */
+    /** Signed continuation from next_cursor. Bound to route, filters, caller and visibility; invalid or old tokens return invalid_cursor. Person appearance publication pages use a media-id insertion fence; aggregate sorts remain live. */
     cursor?: string;
     /** Substring filter over the row's text columns (e.g. video title, channel name, description). */
     q?: string;
@@ -19,4 +19,8 @@ export interface ChannelsRelatedRequest {
     sort?: string;
     /** Sort direction. Default desc. */
     order?: Arcmira.channels.ChannelsRelatedRequestOrder;
+    /** Person relationship lens: guest appearances or inbound mentions. */
+    mode?: Arcmira.channels.ChannelsRelatedRequestMode;
+    /** For person appearances, true lists guest episodes and false lists inbound mentions. */
+    is_appearance?: Arcmira.channels.ChannelsRelatedRequestIsAppearance;
 }

package/dist/cjs/api/resources/channels/resources/related/client/requests/OrganizationsRelatedRequest.d.ts

@@ -9,7 +9,7 @@ export interface OrganizationsRelatedRequest {
     /** The entity slug: the last segment of its arcmira.com page URL, as EntityRef.slug carries it. */
     slug: string;
     limit?: number;
-    /** Opaque cursor from a previous page's next_cursor. */
+    /** Signed continuation from next_cursor. Bound to route, filters, caller and visibility; invalid or old tokens return invalid_cursor. Person appearance publication pages use a media-id insertion fence; aggregate sorts remain live. */
     cursor?: string;
     /** Substring filter over the row's text columns (e.g. video title, channel name, description). */
     q?: string;
@@ -19,4 +19,8 @@ export interface OrganizationsRelatedRequest {
     sort?: string;
     /** Sort direction. Default desc. */
     order?: Arcmira.channels.OrganizationsRelatedRequestOrder;
+    /** Person relationship lens: guest appearances or inbound mentions. */
+    mode?: Arcmira.channels.OrganizationsRelatedRequestMode;
+    /** For person appearances, true lists guest episodes and false lists inbound mentions. */
+    is_appearance?: Arcmira.channels.OrganizationsRelatedRequestIsAppearance;
 }

package/dist/cjs/api/resources/channels/resources/related/client/requests/PeopleRelatedRequest.d.ts

@@ -9,7 +9,7 @@ export interface PeopleRelatedRequest {
     /** The entity slug: the last segment of its arcmira.com page URL, as EntityRef.slug carries it. */
     slug: string;
     limit?: number;
-    /** Opaque cursor from a previous page's next_cursor. */
+    /** Signed continuation from next_cursor. Bound to route, filters, caller and visibility; invalid or old tokens return invalid_cursor. Person appearance publication pages use a media-id insertion fence; aggregate sorts remain live. */
     cursor?: string;
     /** Substring filter over the row's text columns (e.g. video title, channel name, description). */
     q?: string;
@@ -19,4 +19,8 @@ export interface PeopleRelatedRequest {
     sort?: string;
     /** Sort direction. Default desc. */
     order?: Arcmira.channels.PeopleRelatedRequestOrder;
+    /** Person relationship lens: guest appearances or inbound mentions. */
+    mode?: Arcmira.channels.PeopleRelatedRequestMode;
+    /** For person appearances, true lists guest episodes and false lists inbound mentions. */
+    is_appearance?: Arcmira.channels.PeopleRelatedRequestIsAppearance;
 }

package/dist/cjs/api/resources/channels/resources/related/client/requests/ProductsRelatedRequest.d.ts

@@ -9,7 +9,7 @@ export interface ProductsRelatedRequest {
     /** The entity slug: the last segment of its arcmira.com page URL, as EntityRef.slug carries it. */
     slug: string;
     limit?: number;
-    /** Opaque cursor from a previous page's next_cursor. */
+    /** Signed continuation from next_cursor. Bound to route, filters, caller and visibility; invalid or old tokens return invalid_cursor. Person appearance publication pages use a media-id insertion fence; aggregate sorts remain live. */
     cursor?: string;
     /** Substring filter over the row's text columns (e.g. video title, channel name, description). */
     q?: string;
@@ -19,4 +19,8 @@ export interface ProductsRelatedRequest {
     sort?: string;
     /** Sort direction. Default desc. */
     order?: Arcmira.channels.ProductsRelatedRequestOrder;
+    /** Person relationship lens: guest appearances or inbound mentions. */
+    mode?: Arcmira.channels.ProductsRelatedRequestMode;
+    /** For person appearances, true lists guest episodes and false lists inbound mentions. */
+    is_appearance?: Arcmira.channels.ProductsRelatedRequestIsAppearance;
 }

package/dist/cjs/api/resources/channels/resources/related/client/requests/TopicsRelatedRequest.d.ts

@@ -9,7 +9,7 @@ export interface TopicsRelatedRequest {
     /** The entity slug: the last segment of its arcmira.com page URL, as EntityRef.slug carries it. */
     slug: string;
     limit?: number;
-    /** Opaque cursor from a previous page's next_cursor. */
+    /** Signed continuation from next_cursor. Bound to route, filters, caller and visibility; invalid or old tokens return invalid_cursor. Person appearance publication pages use a media-id insertion fence; aggregate sorts remain live. */
     cursor?: string;
     /** Substring filter over the row's text columns (e.g. video title, channel name, description). */
     q?: string;
@@ -19,4 +19,8 @@ export interface TopicsRelatedRequest {
     sort?: string;
     /** Sort direction. Default desc. */
     order?: Arcmira.channels.TopicsRelatedRequestOrder;
+    /** Person relationship lens: guest appearances or inbound mentions. */
+    mode?: Arcmira.channels.TopicsRelatedRequestMode;
+    /** For person appearances, true lists guest episodes and false lists inbound mentions. */
+    is_appearance?: Arcmira.channels.TopicsRelatedRequestIsAppearance;
 }

package/dist/cjs/api/resources/channels/resources/related/types/ChannelsRelatedRequestIsAppearance.d.ts

@@ -0,0 +1,8 @@
+/** For person appearances, true lists guest episodes and false lists inbound mentions. */
+export declare const ChannelsRelatedRequestIsAppearance: {
+    readonly Zero: "0";
+    readonly One: "1";
+    readonly True: "true";
+    readonly False: "false";
+};
+export type ChannelsRelatedRequestIsAppearance = (typeof ChannelsRelatedRequestIsAppearance)[keyof typeof ChannelsRelatedRequestIsAppearance];

package/dist/cjs/api/resources/channels/resources/related/types/ChannelsRelatedRequestIsAppearance.js

@@ -0,0 +1,11 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelsRelatedRequestIsAppearance = void 0;
+/** For person appearances, true lists guest episodes and false lists inbound mentions. */
+exports.ChannelsRelatedRequestIsAppearance = {
+    Zero: "0",
+    One: "1",
+    True: "true",
+    False: "false",
+};

package/dist/cjs/api/resources/channels/resources/related/types/ChannelsRelatedRequestMode.d.ts

@@ -0,0 +1,6 @@
+/** Person relationship lens: guest appearances or inbound mentions. */
+export declare const ChannelsRelatedRequestMode: {
+    readonly Appearances: "appearances";
+    readonly Mentions: "mentions";
+};
+export type ChannelsRelatedRequestMode = (typeof ChannelsRelatedRequestMode)[keyof typeof ChannelsRelatedRequestMode];

package/dist/cjs/api/resources/channels/resources/related/types/ChannelsRelatedRequestMode.js

@@ -0,0 +1,9 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelsRelatedRequestMode = void 0;
+/** Person relationship lens: guest appearances or inbound mentions. */
+exports.ChannelsRelatedRequestMode = {
+    Appearances: "appearances",
+    Mentions: "mentions",
+};

package/dist/cjs/api/resources/channels/resources/related/types/OrganizationsRelatedRequestIsAppearance.d.ts

@@ -0,0 +1,8 @@
+/** For person appearances, true lists guest episodes and false lists inbound mentions. */
+export declare const OrganizationsRelatedRequestIsAppearance: {
+    readonly Zero: "0";
+    readonly One: "1";
+    readonly True: "true";
+    readonly False: "false";
+};
+export type OrganizationsRelatedRequestIsAppearance = (typeof OrganizationsRelatedRequestIsAppearance)[keyof typeof OrganizationsRelatedRequestIsAppearance];

package/dist/cjs/api/resources/channels/resources/related/types/OrganizationsRelatedRequestIsAppearance.js

@@ -0,0 +1,11 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrganizationsRelatedRequestIsAppearance = void 0;
+/** For person appearances, true lists guest episodes and false lists inbound mentions. */
+exports.OrganizationsRelatedRequestIsAppearance = {
+    Zero: "0",
+    One: "1",
+    True: "true",
+    False: "false",
+};