@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/imageLibrary.md

@@ -0,0 +1,569 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.imageLibrary`: Image Library
+
+14 operations (4 read, 8 write, 2 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.imageLibrary.*` 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: [imageLibrary.d.ts](imageLibrary.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`commitGeneratedImage`](#op-commitgeneratedimage) | `POST /api/v1/image-library/generated/{image_id}/commit` | write | `campaigns:write` | Commit Generated Image |
+| [`deleteLibraryImage`](#op-deletelibraryimage) | `DELETE /api/v1/image-library/{image_id}` | destructive | `campaigns:delete` | Delete Library Image |
+| [`discardGeneratedImage`](#op-discardgeneratedimage) | `DELETE /api/v1/image-library/generated/{image_id}` | destructive | `campaigns:delete` | Discard Generated Image |
+| [`extractImagesFromAllPages`](#op-extractimagesfromallpages) | `POST /api/v1/image-library/extract-all-pages` | write | `campaigns:write` | Extract Images From All Pages |
+| [`extractImagesFromWebsite`](#op-extractimagesfromwebsite) | `POST /api/v1/image-library/extract` | write | `campaigns:write` | Extract Images From Website |
+| [`getImageExtractionStatus`](#op-getimageextractionstatus) | `GET /api/v1/image-library/extract/status/{task_id}` | read | `campaigns:read` | Get Image Extraction Status |
+| [`listLibraryImageCategories`](#op-listlibraryimagecategories) | `GET /api/v1/image-library/categories` | read | `campaigns:read` | List Library Image Categories |
+| [`listLibraryImages`](#op-listlibraryimages) | `GET /api/v1/image-library` | read | `campaigns:read` | List Library Images |
+| [`mergeLibraryDuplicates`](#op-mergelibraryduplicates) | `POST /api/v1/image-library/duplicates/merge` | write | `campaigns:write` | Merge Library Duplicates |
+| [`scanLibraryDuplicates`](#op-scanlibraryduplicates) | `POST /api/v1/image-library/duplicates/scan` | read | `campaigns:read` | Scan Library Duplicates |
+| [`setLibraryImageAltText`](#op-setlibraryimagealttext) | `PATCH /api/v1/image-library/{image_id}/alt-text` | write | `campaigns:write` | Set Library Image Alt Text |
+| [`setLibraryImageCategory`](#op-setlibraryimagecategory) | `PATCH /api/v1/image-library/{image_id}/category` | write | `campaigns:write` | Set Library Image Category |
+| [`setLibraryImageFeedback`](#op-setlibraryimagefeedback) | `PATCH /api/v1/image-library/{image_id}/feedback` | write | `campaigns:write` | Set Library Image Feedback |
+| [`setLibraryImageTags`](#op-setlibraryimagetags) | `PATCH /api/v1/image-library/{image_id}/tags` | write | `campaigns:write` | Set Library Image Tags |
+
+---
+
+<a id="op-commitgeneratedimage"></a>
+
+### `g8.api.imageLibrary.commitGeneratedImage(input)`
+
+**Commit Generated Image**
+
+- HTTP: `POST /api/v1/image-library/generated/{image_id}/commit`
+- operationId: `commit_generated_image_image_library_generated__image_id__commit_post` (also callable as `g8.api.call("commit_generated_image_image_library_generated__image_id__commit_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Promote an AI DRAFT into a durable library asset. FREE.
+
+A draft lives on a 24-hour TTL and its storage object is swept. Commit it
+before referencing it from a page you intend to publish, or the page ends
+up pointing at an object that has been collected.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.commitGeneratedImage({ path: { image_id: "id" } });
+```
+
+---
+
+<a id="op-deletelibraryimage"></a>
+
+### `g8.api.imageLibrary.deleteLibraryImage(input)`
+
+**Delete Library Image**
+
+- HTTP: `DELETE /api/v1/image-library/{image_id}`
+- operationId: `delete_library_image_image_library__image_id__delete` (also callable as `g8.api.call("delete_library_image_image_library__image_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete a durable image from the library.
+
+ANY published page or live ad still pointing at it breaks. `campaigns:delete`,
+which is the app's own gate and a deliberately narrower one than the rest
+of this router carries.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.imageLibrary.deleteLibraryImage({ path: { image_id: "id" } });
+```
+
+---
+
+<a id="op-discardgeneratedimage"></a>
+
+### `g8.api.imageLibrary.discardGeneratedImage(input)`
+
+**Discard Generated Image**
+
+- HTTP: `DELETE /api/v1/image-library/generated/{image_id}`
+- operationId: `discard_generated_image_image_library_generated__image_id__delete` (also callable as `g8.api.call("discard_generated_image_image_library_generated__image_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Throw an uncommitted AI draft away, and its storage object with it.
+
+Only DRAFTS. A committed asset is `DELETE /image-library/{image_id}`,
+which is gated differently on purpose.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `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.imageLibrary.discardGeneratedImage({ path: { image_id: "id" } });
+```
+
+---
+
+<a id="op-extractimagesfromallpages"></a>
+
+### `g8.api.imageLibrary.extractImagesFromAllPages(input?)`
+
+**Extract Images From All Pages**
+
+- HTTP: `POST /api/v1/image-library/extract-all-pages`
+- operationId: `extract_images_from_all_pages_image_library_extract_all_pages_post` (also callable as `g8.api.call("extract_images_from_all_pages_image_library_extract_all_pages_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Run the extraction over EVERY stored content page. FREE, but broad.
+
+No credit is spent and no site is re-fetched - it reads the HTML already
+stored against each content page. The cost is in the library: on a large
+inventory this can add a great many images at once, and there is no
+per-page filter. `POST /extract` is the bounded version.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.extractImagesFromAllPages();
+```
+
+---
+
+<a id="op-extractimagesfromwebsite"></a>
+
+### `g8.api.imageLibrary.extractImagesFromWebsite(input)`
+
+**Extract Images From Website**
+
+- HTTP: `POST /api/v1/image-library/extract`
+- operationId: `extract_images_from_website_image_library_extract_post` (also callable as `g8.api.call("extract_images_from_website_image_library_extract_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Pull every image off one page into the library. FREE - no model runs.
+
+It fetches the URL server-side, so the page must be publicly reachable.
+`min_width` / `min_height` are what keep the icons and tracking pixels
+out; lowering them floods the library rather than enriching it.
+
+Asynchronous - it returns once the extraction is dispatched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ExtractImagesRequest` | yes | Request body; fields below. |
+
+Body fields (`ExtractImagesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.url` | `string` | yes |  |
+| `body.min_height` | `integer` | no | default `200` |
+| `body.min_width` | `integer` | no | default `200` |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.extractImagesFromWebsite({ body: { url: "https://example.com" } });
+```
+
+---
+
+<a id="op-getimageextractionstatus"></a>
+
+### `g8.api.imageLibrary.getImageExtractionStatus(input)`
+
+**Get Image Extraction Status**
+
+- HTTP: `GET /api/v1/image-library/extract/status/{task_id}`
+- operationId: `get_image_extraction_status_image_library_extract_status__task_id__get` (also callable as `g8.api.call("get_image_extraction_status_image_library_extract_status__task_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Progress of a background image extraction. FREE - the poll target.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id returned by `POST /image-library/extract`. |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.getImageExtractionStatus({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-listlibraryimagecategories"></a>
+
+### `g8.api.imageLibrary.listLibraryImageCategories(input?)`
+
+**List Library Image Categories**
+
+- HTTP: `GET /api/v1/image-library/categories`
+- operationId: `list_library_image_categories_image_library_categories_get` (also callable as `g8.api.call("list_library_image_categories_image_library_categories_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Image counts by category. FREE - the vocabulary the filters accept.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.listLibraryImageCategories();
+```
+
+---
+
+<a id="op-listlibraryimages"></a>
+
+### `g8.api.imageLibrary.listLibraryImages(input?)`
+
+**List Library Images**
+
+- HTTP: `GET /api/v1/image-library`
+- operationId: `list_library_images_image_library_get` (also callable as `g8.api.call("list_library_images_image_library_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The org's image library. FREE.
+
+The SOURCE of the `library_image_id` that `POST /ad-creatives` and
+`POST /ad-creatives/{id}/set-image` accept.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.category` | `string \| null` | no | From `GET /image-library/categories`. |
+| `query.campaign_id` | `string \| null` | no |  |
+| `query.source_url` | `string \| null` | no | Only images pulled from this page. |
+| `query.source` | `string \| null` | no | How the image got here - extract, upload, ai. |
+| `query.include_archived` | `boolean` | no | default `false` |
+| `query.limit` | `integer` | no | default `100` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_StudioContentListPayload_`: the envelope `{ data: StudioContentListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioContentListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.listLibraryImages();
+```
+
+---
+
+<a id="op-mergelibraryduplicates"></a>
+
+### `g8.api.imageLibrary.mergeLibraryDuplicates(input)`
+
+**Merge Library Duplicates**
+
+- HTTP: `POST /api/v1/image-library/duplicates/merge`
+- operationId: `merge_library_duplicates_image_library_duplicates_merge_post` (also callable as `g8.api.call("merge_library_duplicates_image_library_duplicates_merge_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Merge duplicates into one keeper. The duplicates are REMOVED.
+
+References to a duplicate are re-pointed at the keeper first, so nothing
+that used one breaks. Gated like a delete (`campaigns:delete`), because
+it is one - the app's own `_require_library_management`.
+
+Spends nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ImageMergeDuplicatesRequest` | yes | Request body; fields below. |
+
+Body fields (`ImageMergeDuplicatesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.duplicate_ids` | `Array<string (uuid)>` | yes | min items 1, max items 100 |
+| `body.keeper_id` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.mergeLibraryDuplicates({
+  body: {
+    duplicate_ids: ["00000000-0000-0000-0000-000000000000"],
+    keeper_id: "00000000-0000-0000-0000-000000000000",
+  },
+});
+```
+
+---
+
+<a id="op-scanlibraryduplicates"></a>
+
+### `g8.api.imageLibrary.scanLibraryDuplicates(input?)`
+
+**Scan Library Duplicates**
+
+- HTTP: `POST /api/v1/image-library/duplicates/scan`
+- operationId: `scan_library_duplicates_image_library_duplicates_scan_post` (also callable as `g8.api.call("scan_library_duplicates_image_library_duplicates_scan_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Find groups of duplicate images in the library. FREE, and changes nothing.
+
+The input to `POST /image-library/duplicates/merge`: each group names the
+images that are the same picture.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.scanLibraryDuplicates();
+```
+
+---
+
+<a id="op-setlibraryimagealttext"></a>
+
+### `g8.api.imageLibrary.setLibraryImageAltText(input)`
+
+**Set Library Image Alt Text**
+
+- HTTP: `PATCH /api/v1/image-library/{image_id}/alt-text`
+- operationId: `set_library_image_alt_text_image_library__image_id__alt_text_patch` (also callable as `g8.api.call("set_library_image_alt_text_image_library__image_id__alt_text_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Set the alt text. FREE.
+
+It is ALSO the library display name, so this is not only an accessibility
+field - changing it renames the image everywhere Studio shows it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+| `body` | `ImageAltTextRequest` | yes | Request body; fields below. |
+
+Body fields (`ImageAltTextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.alt_text` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.setLibraryImageAltText({ path: { image_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-setlibraryimagecategory"></a>
+
+### `g8.api.imageLibrary.setLibraryImageCategory(input)`
+
+**Set Library Image Category**
+
+- HTTP: `PATCH /api/v1/image-library/{image_id}/category`
+- operationId: `set_library_image_category_image_library__image_id__category_patch` (also callable as `g8.api.call("set_library_image_category_image_library__image_id__category_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Recategorise an image. FREE. Categories come from `/categories`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+| `body` | `ImageCategoryRequest` | yes | Request body; fields below. |
+
+Body fields (`ImageCategoryRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.category` | `string` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.setLibraryImageCategory({ path: { image_id: "id" }, body: { category: "example" } });
+```
+
+---
+
+<a id="op-setlibraryimagefeedback"></a>
+
+### `g8.api.imageLibrary.setLibraryImageFeedback(input)`
+
+**Set Library Image Feedback**
+
+- HTTP: `PATCH /api/v1/image-library/{image_id}/feedback`
+- operationId: `set_library_image_feedback_image_library__image_id__feedback_patch` (also callable as `g8.api.call("set_library_image_feedback_image_library__image_id__feedback_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Thumbs up or down on an image. FREE.
+
+`feedback: null` CLEARS the existing rating rather than leaving it - there
+is no separate delete.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+| `body` | `ImageFeedbackRequest` | yes | Request body; fields below. |
+
+Body fields (`ImageFeedbackRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.feedback` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.setLibraryImageFeedback({ path: { image_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-setlibraryimagetags"></a>
+
+### `g8.api.imageLibrary.setLibraryImageTags(input)`
+
+**Set Library Image Tags**
+
+- HTTP: `PATCH /api/v1/image-library/{image_id}/tags`
+- operationId: `set_library_image_tags_image_library__image_id__tags_patch` (also callable as `g8.api.call("set_library_image_tags_image_library__image_id__tags_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+REPLACE an image's tags (e.g. `main_logo`, `dark_mode`). FREE.
+
+The list you send is the whole new set; send `[]` to clear them.
+Generation reads these tags to pick the right logo variant.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.image_id` | `string` | yes | Image id (UUID). |
+| `body` | `ImageTagsRequest` | yes | Request body; fields below. |
+
+Body fields (`ImageTagsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.tags` | `Array<string>` | yes |  |
+
+**Returns** `ApiResponse_StudioContentPayload_`: the envelope `{ data: StudioContentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.imageLibrary.setLibraryImageTags({ path: { image_id: "id" }, body: { tags: ["example"] } });
+```