@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/orgVideos.d.ts

@@ -0,0 +1,184 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.orgVideos` (Org Videos): 6 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"delete_org_video_org_videos__video_id__delete">;
+ *
+ * Reference with examples: orgVideos.md
+ */
+/* eslint-disable */
+
+/** `g8.api.orgVideos.<member>` -> the operationId it calls. */
+export interface OrgVideosMembers {
+  deleteOrgVideo: "delete_org_video_org_videos__video_id__delete";
+  generateOrgVideo: "generate_org_video_org_videos_generate_post";
+  getOrgVideo: "get_org_video_org_videos__video_id__get";
+  listOrgVideos: "list_org_videos_org_videos_get";
+  updateOrgVideo: "update_org_video_org_videos__video_id__patch";
+  uploadOrgVideo: "upload_org_video_org_videos_upload_post";
+}
+
+/** Input and output of every `g8.api.orgVideos` operation, keyed by operationId. */
+export interface OrgVideosOperations {
+  /**
+   * DELETE /org-videos/{video_id}
+   * Delete Org Video
+   * tier: destructive · scope: campaigns:delete
+   */
+  delete_org_video_org_videos__video_id__delete: {
+    input: {
+    path: {
+      /** Video id. */
+      video_id: string;
+    };
+    query?: {
+      /** Also remove the stored file. Irreversible. */
+      hard?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgVideoPayload_;
+  };
+  /**
+   * POST /org-videos/generate
+   * Generate Org Video
+   * tier: billable · scope: campaigns:run
+   */
+  generate_org_video_org_videos_generate_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OrgVideoGenerateRequest;
+  };
+    output: ApiResponse_OrgVideoPayload_;
+  };
+  /**
+   * GET /org-videos/{video_id}
+   * Get Org Video
+   * tier: read · scope: campaigns:read
+   */
+  get_org_video_org_videos__video_id__get: {
+    input: {
+    path: {
+      /** Video id. */
+      video_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgVideoPayload_;
+  };
+  /**
+   * GET /org-videos
+   * List Org Videos
+   * tier: read · scope: campaigns:read
+   */
+  list_org_videos_org_videos_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgVideoListPayload_;
+  };
+  /**
+   * PATCH /org-videos/{video_id}
+   * Update Org Video
+   * tier: write · scope: campaigns:write
+   */
+  update_org_video_org_videos__video_id__patch: {
+    input: {
+    path: {
+      /** Video id. */
+      video_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: OrgVideoUpdateRequest;
+  };
+    output: ApiResponse_OrgVideoPayload_;
+  };
+  /**
+   * POST /org-videos/upload
+   * Upload Org Video
+   * tier: write · scope: campaigns:write
+   */
+  upload_org_video_org_videos_upload_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgVideoPayload_;
+  };
+}
+
+// 9 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_OrgVideoListPayload_ {
+  data: OrgVideoListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_OrgVideoPayload_ {
+  data: OrgVideoPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface OrgVideoGenerateRequest {
+  storyboard: OrgVideoStoryboard;
+  template_id?: string;
+  title?: string | null;
+}
+
+/** The org's library videos under `items`. */
+export interface OrgVideoListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/** A library video. `generation` carries render progress for generated videos. */
+export type OrgVideoPayload = Record<string, unknown>;
+
+export interface OrgVideoShot {
+  /** A READY Studio clip. */
+  clip_id: string;
+  /** Trim start, seconds. */
+  in_s?: number | null;
+  /** Trim end, seconds. */
+  out_s?: number | null;
+}
+
+export interface OrgVideoStoryboard {
+  /** Copy slot id -> text. The `plain` template renders none. */
+  copy?: Record<string, string>;
+  shots?: Array<OrgVideoShot>;
+}
+
+export interface OrgVideoUpdateRequest {
+  alt_text?: string | null;
+  poster_url?: string | null;
+  tags?: Array<string> | null;
+  title?: string | null;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}

package/docs/api/orgVideos.md

@@ -0,0 +1,252 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.orgVideos`: Org Videos
+
+6 operations (2 read, 2 write, 1 destructive, 1 billable).
+
+No hand-written client covers this area. Call it through `g8.api.orgVideos.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [orgVideos.d.ts](orgVideos.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`deleteOrgVideo`](#op-deleteorgvideo) | `DELETE /api/v1/org-videos/{video_id}` | destructive | `campaigns:delete` | Delete Org Video |
+| [`generateOrgVideo`](#op-generateorgvideo) | `POST /api/v1/org-videos/generate` | billable | `campaigns:run` | Generate Org Video |
+| [`getOrgVideo`](#op-getorgvideo) | `GET /api/v1/org-videos/{video_id}` | read | `campaigns:read` | Get Org Video |
+| [`listOrgVideos`](#op-listorgvideos) | `GET /api/v1/org-videos` | read | `campaigns:read` | List Org Videos |
+| [`updateOrgVideo`](#op-updateorgvideo) | `PATCH /api/v1/org-videos/{video_id}` | write | `campaigns:write` | Update Org Video |
+| [`uploadOrgVideo`](#op-uploadorgvideo) | `POST /api/v1/org-videos/upload` | write | `campaigns:write` | Upload Org Video |
+
+---
+
+<a id="op-deleteorgvideo"></a>
+
+### `g8.api.orgVideos.deleteOrgVideo(input)`
+
+**Delete Org Video**
+
+- HTTP: `DELETE /api/v1/org-videos/{video_id}`
+- operationId: `delete_org_video_org_videos__video_id__delete` (also callable as `g8.api.call("delete_org_video_org_videos__video_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete a video - soft by default, so it can be recovered; `hard=true` removes the file.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.video_id` | `string` | yes | Video id. |
+| `query.hard` | `boolean` | no | Also remove the stored file. Irreversible. default `false` |
+
+**Returns** `ApiResponse_OrgVideoPayload_`: the envelope `{ data: OrgVideoPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.orgVideos.deleteOrgVideo({ path: { video_id: "id" } });
+```
+
+---
+
+<a id="op-generateorgvideo"></a>
+
+### `g8.api.orgVideos.generateOrgVideo(input)`
+
+**Generate Org Video**
+
+- HTTP: `POST /api/v1/org-videos/generate`
+- operationId: `generate_org_video_org_videos_generate_post` (also callable as `g8.api.call("generate_org_video_org_videos_generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Render a storyboard of ready clips into a library video (charges the render fee).
+
+Returns at once with the video queued; poll `GET /org-videos/{video_id}`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OrgVideoGenerateRequest` | yes | Request body; fields below. |
+
+Body fields (`OrgVideoGenerateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.storyboard` | `OrgVideoStoryboard` | yes |  |
+| `body.template_id` | `string` | no | default `"plain"`, min length 1, max length 40 |
+| `body.title` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_OrgVideoPayload_`: the envelope `{ data: OrgVideoPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.orgVideos.generateOrgVideo({ body: { storyboard: {} } });
+```
+
+---
+
+<a id="op-getorgvideo"></a>
+
+### `g8.api.orgVideos.getOrgVideo(input)`
+
+**Get Org Video**
+
+- HTTP: `GET /api/v1/org-videos/{video_id}`
+- operationId: `get_org_video_org_videos__video_id__get` (also callable as `g8.api.call("get_org_video_org_videos__video_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One video. Poll this for a generated video's render progress.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.video_id` | `string` | yes | Video id. |
+
+**Returns** `ApiResponse_OrgVideoPayload_`: the envelope `{ data: OrgVideoPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.orgVideos.getOrgVideo({ path: { video_id: "id" } });
+```
+
+---
+
+<a id="op-listorgvideos"></a>
+
+### `g8.api.orgVideos.listOrgVideos(input?)`
+
+**List Org Videos**
+
+- HTTP: `GET /api/v1/org-videos`
+- operationId: `list_org_videos_org_videos_get` (also callable as `g8.api.call("list_org_videos_org_videos_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The org's library videos, newest first.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgVideoListPayload_`: the envelope `{ data: OrgVideoListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgVideoListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.orgVideos.listOrgVideos();
+```
+
+---
+
+<a id="op-updateorgvideo"></a>
+
+### `g8.api.orgVideos.updateOrgVideo(input)`
+
+**Update Org Video**
+
+- HTTP: `PATCH /api/v1/org-videos/{video_id}`
+- operationId: `update_org_video_org_videos__video_id__patch` (also callable as `g8.api.call("update_org_video_org_videos__video_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Edit a video's title, alt text, poster or tags. The file itself is immutable.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.video_id` | `string` | yes | Video id. |
+| `body` | `OrgVideoUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`OrgVideoUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.alt_text` | `string \| null` | no |  |
+| `body.poster_url` | `string \| null` | no |  |
+| `body.tags` | `Array<string> \| null` | no |  |
+| `body.title` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_OrgVideoPayload_`: the envelope `{ data: OrgVideoPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.orgVideos.updateOrgVideo({ path: { video_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-uploadorgvideo"></a>
+
+### `g8.api.orgVideos.uploadOrgVideo(input?)`
+
+**Upload Org Video**
+
+- HTTP: `POST /api/v1/org-videos/upload`
+- operationId: `upload_org_video_org_videos_upload_post` (also callable as `g8.api.call("upload_org_video_org_videos_upload_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Upload a video to the library. An identical file already there is returned instead.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgVideoPayload_`: the envelope `{ data: OrgVideoPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.orgVideos.uploadOrgVideo();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-orgvideostoryboard"></a>
+
+### `OrgVideoStoryboard`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `copy` | `Record<string, string>` | no | Copy slot id -> text. The `plain` template renders none. |
+| `shots` | `Array<OrgVideoShot>` | no |  |