@graph8/sdk 0.295.2 → 0.302.0

package/docs/api/seo.md

@@ -2,7 +2,7 @@
 
 # `g8.api.seo`: SEO
 
-11 operations (5 read, 2 write, 4 billable).
+14 operations (8 read, 2 write, 4 billable).
 
 No hand-written client covers this area. Call it through `g8.api.seo.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
 
@@ -27,7 +27,10 @@ Exact TypeScript types for every operation on this page, and every schema they u
 | [`getSeoDomainBacklinks`](#op-getseodomainbacklinks) | `GET /api/v1/seo/domains/{domain}/backlinks` | billable | `intent:run` | Get Seo Domain Backlinks |
 | [`getSeoDomainOverview`](#op-getseodomainoverview) | `GET /api/v1/seo/domains/{domain}/overview` | billable | `intent:run` | Get Seo Domain Overview |
 | [`getSeoRankHistory`](#op-getseorankhistory) | `GET /api/v1/seo/rank-tracking/{keyword_id}/history` | read | `intent:read` | Get Seo Rank History |
+| [`getSeoTrackedDomain`](#op-getseotrackeddomain) | `GET /api/v1/seo/domains/tracked/{domain}` | read | `intent:read` | Get Seo Tracked Domain |
 | [`listSeoAudits`](#op-listseoaudits) | `GET /api/v1/seo/audits` | read | `intent:read` | List Seo Audits |
+| [`listSeoDomainPages`](#op-listseodomainpages) | `GET /api/v1/seo/domains/tracked/{domain}/pages` | read | `intent:read` | List Seo Domain Pages |
+| [`listSeoTrackedDomains`](#op-listseotrackeddomains) | `GET /api/v1/seo/domains/tracked` | read | `intent:read` | List Seo Tracked Domains |
 | [`listSeoTrackedKeywords`](#op-listseotrackedkeywords) | `GET /api/v1/seo/rank-tracking` | read | `intent:read` | List Seo Tracked Keywords |
 | [`removeSeoTrackedKeywords`](#op-removeseotrackedkeywords) | `POST /api/v1/seo/rank-tracking/keywords/remove` | write | `intent:write` | Remove Seo Tracked Keywords |
 | [`researchSeoKeywords`](#op-researchseokeywords) | `POST /api/v1/seo/keywords/research` | billable | `intent:run` | Research Seo Keywords |
@@ -258,6 +261,59 @@ const result = await g8.api.seo.getSeoRankHistory({ path: { keyword_id: "0000000
 
 ---
 
+<a id="op-getseotrackeddomain"></a>
+
+### `g8.api.seo.getSeoTrackedDomain(input)`
+
+**Get Seo Tracked Domain**
+
+- HTTP: `GET /api/v1/seo/domains/tracked/{domain}`
+- operationId: `get_seo_tracked_domain_seo_domains_tracked__domain__get` (also callable as `g8.api.call("get_seo_tracked_domain_seo_domains_tracked__domain__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. One saved domain's snapshot: overview, top keywords, top pages, backlinks.
+
+Rendered from what the app last stored; it never calls the provider. 404
+for a domain this organisation does not track. `snapshot_at` says how
+old the snapshot is; it is null until the domain is first refreshed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain` | `string` | yes | A saved domain from `GET /seo/domains/tracked`. |
+
+**Returns** `ApiResponse_SeoTrackedDomainDetail_`: the envelope `{ data: SeoTrackedDomainDetail, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoTrackedDomainDetail` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `kind` | `"own" \| "competitor"` | yes |  |
+| `backlinks` | `SeoBacklinksOverview \| null` | no |  |
+| `change_30d` | `SeoDomainChange \| null` | no |  |
+| `data_freshness` | `string` | no | default `"labs-30-90d"` |
+| `is_primary` | `boolean` | no | default `false` |
+| `metrics` | `SeoTrackedDomainMetrics \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `overview` | `Record<string, unknown> \| null` | no |  |
+| `refreshed` | `boolean` | no | default `false` |
+| `snapshot_at` | `string (date-time) \| null` | no |  |
+| `top_keywords` | `Array<Record<string, unknown>>` | no | default `[]` |
+| `top_pages` | `Array<Record<string, unknown>>` | no | default `[]` |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoTrackedDomain({ path: { domain: "acme.com" } });
+```
+
+---
+
 <a id="op-listseoaudits"></a>
 
 ### `g8.api.seo.listSeoAudits(input?)`
@@ -306,6 +362,102 @@ const result = await g8.api.seo.listSeoAudits();
 
 ---
 
+<a id="op-listseodomainpages"></a>
+
+### `g8.api.seo.listSeoDomainPages(input)`
+
+**List Seo Domain Pages**
+
+- HTTP: `GET /api/v1/seo/domains/tracked/{domain}/pages`
+- operationId: `list_seo_domain_pages_seo_domains_tracked__domain__pages_get` (also callable as `g8.api.call("list_seo_domain_pages_seo_domains_tracked__domain__pages_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The saved ranking pages of a tracked domain, paged and sorted.
+
+Read only: it never calls the provider. `refreshed_at` is null when the
+pages were never fetched (fetching them is a paid action in the app).
+An unknown sort column is a 422 naming the allowed ones.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.domain` | `string` | yes | A saved domain from `GET /seo/domains/tracked`. |
+| `query.offset` | `integer` | no | Rows to skip (the saved pages are capped at 1,000). default `0` |
+| `query.limit` | `integer` | no | Rows to return. default `50` |
+| `query.sort` | `string` | no | Sort column: estimated_traffic, ranking_keywords_count, best_position, url, traffic_change_30d or audit_issues. default `"estimated_traffic"` |
+| `query.order` | `"asc" \| "desc"` | no | default `"desc"` |
+| `query.q` | `string \| null` | no | Only pages whose URL contains this text. |
+
+**Returns** `ApiResponse_SeoDomainPages_`: the envelope `{ data: SeoDomainPages, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoDomainPages` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cap` | `integer` | yes |  |
+| `rows` | `Array<SeoDomainPage>` | yes |  |
+| `total` | `integer` | yes |  |
+| `audit_completed_at` | `string (date-time) \| null` | no |  |
+| `refreshed_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.listSeoDomainPages({ path: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-listseotrackeddomains"></a>
+
+### `g8.api.seo.listSeoTrackedDomains(input?)`
+
+**List Seo Tracked Domains**
+
+- HTTP: `GET /api/v1/seo/domains/tracked`
+- operationId: `list_seo_tracked_domains_seo_domains_tracked_get` (also callable as `g8.api.call("list_seo_tracked_domains_seo_domains_tracked_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The SEO overview: every saved domain with its last snapshot.
+
+Own domains first (the primary one first), then the Radar competitors
+shown beside them, each with its saved metrics and 30-day change. Also
+carries what each PAID refresh would cost (`refresh_credits`,
+`pages_max_credits`, `page_keywords_credits`), so a caller can quote a
+price without spending anything. An organisation whose SEO storage is
+still provisioning gets an empty list, matching the app.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SeoTrackedDomains_`: the envelope `{ data: SeoTrackedDomains, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoTrackedDomains` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domains` | `Array<SeoTrackedDomain>` | yes |  |
+| `max_own_domains` | `integer` | yes |  |
+| `page_keywords_credits` | `integer` | yes |  |
+| `page_keywords_limit` | `integer` | yes |  |
+| `pages_cap` | `integer` | yes |  |
+| `pages_max_credits` | `integer` | yes |  |
+| `refresh_credits` | `integer` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.listSeoTrackedDomains();
+```
+
+---
+
 <a id="op-listseotrackedkeywords"></a>
 
 ### `g8.api.seo.listSeoTrackedKeywords(input?)`
@@ -621,6 +773,34 @@ Mirrors `AuditStateDTO` - the plain-language, recovery-oriented view of where an
 | `recovery` | `string` | yes | Plain-language, safe next step (may be empty) |
 | `diagnostic` | `string \| null` | no | Secondary technical detail (raw provider text) |
 
+<a id="type-seodomainchange"></a>
+
+### `SeoDomainChange`
+
+Mirrors `DomainChangeDTO`: the current snapshot against the one nearest 30 days back. `traffic_pct` is null when the baseline traffic was zero.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keywords_delta` | `integer \| null` | no |  |
+| `since` | `string \| null` | no |  |
+| `traffic_pct` | `number \| null` | no |  |
+
+<a id="type-seodomainpage"></a>
+
+### `SeoDomainPage`
+
+Mirrors `DomainPageDTO`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `estimated_traffic` | `number` | yes |  |
+| `ranking_keywords_count` | `integer` | yes |  |
+| `url` | `string` | yes |  |
+| `audit_issues` | `integer \| null` | no |  |
+| `best_position` | `integer \| null` | no |  |
+| `top_keyword` | `string \| null` | no |  |
+| `traffic_change_30d` | `number \| null` | no |  |
+
 <a id="type-seokeywordrow"></a>
 
 ### `SeoKeywordRow`
@@ -658,3 +838,33 @@ Mirrors `TrackKeywordItem`.
 |---|---|---|---|
 | `keyword` | `string` | yes | min length 1, max length 500 |
 | `search_volume` | `integer \| null` | no |  |
+
+<a id="type-seotrackeddomain"></a>
+
+### `SeoTrackedDomain`
+
+Mirrors `TrackedDomainDTO`. `kind` is `own` for the organisation's own sites and `competitor` for the Radar competitors shown beside them.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `kind` | `"own" \| "competitor"` | yes |  |
+| `change_30d` | `SeoDomainChange \| null` | no |  |
+| `is_primary` | `boolean` | no | default `false` |
+| `metrics` | `SeoTrackedDomainMetrics \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `snapshot_at` | `string (date-time) \| null` | no |  |
+
+<a id="type-seotrackeddomainmetrics"></a>
+
+### `SeoTrackedDomainMetrics`
+
+Mirrors `TrackedDomainMetricsDTO`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `authority_score` | `number \| null` | no |  |
+| `estimated_traffic` | `number \| null` | no |  |
+| `organic_keywords` | `integer \| null` | no |  |
+| `referring_domains` | `number \| null` | no |  |
+| `top3_positions` | `integer \| null` | no |  |

package/docs/api/work.d.ts

@@ -1097,7 +1097,7 @@ export interface WorkOperations {
   };
 }
 
-// 122 schemas referenced above (the same as G8Contract.<Name>).
+// 123 schemas referenced above (the same as G8Contract.<Name>).
 
 export interface ApiResponse_WorkActivityPage_ {
   data: WorkActivityPage;
@@ -1558,6 +1558,22 @@ export interface WorkChannelDeleteRequest {
   confirmationName: string;
 }
 
+/**
+ * A channel's icon: a glyph on a color, an emoji, or an uploaded image.
+ *
+ * `glyph` and `color` are ids from the client's curated sets, never raw CSS
+ * or SVG, so nothing a member stores can inject markup or styles into
+ * another member's sidebar. An image is a Work attachment id, never a URL:
+ * readability is re-checked on every read (`readable_attachment_ids`).
+ */
+export interface WorkChannelIcon {
+  attachmentId?: string | null;
+  color?: string | null;
+  emoji?: string | null;
+  glyph?: string | null;
+  type: "glyph" | "emoji" | "image";
+}
+
 /** The channels this credential may read. */
 export interface WorkChannelList {
   /** Channels visible to the caller */
@@ -1591,6 +1607,7 @@ export interface WorkChannelSettingsRequest {
   confirmAgentAccess?: boolean;
   description?: string | null;
   displayName?: string | null;
+  icon?: WorkChannelIcon | null;
   memberUserIds?: Array<string>;
   participantAgentIds?: Array<string>;
   visibility?: ("open" | "private") | null;

package/docs/api/work.md

@@ -2791,6 +2791,7 @@ Body fields (`WorkChannelSettingsRequest`):
 | `body.confirmAgentAccess` | `boolean` | no | default `false` |
 | `body.description` | `string \| null` | no | max length 1000 |
 | `body.displayName` | `string \| null` | no | max length 255 |
+| `body.icon` | `WorkChannelIcon \| null` | no |  |
 | `body.memberUserIds` | `Array<string>` | no | max items 100 |
 | `body.participantAgentIds` | `Array<string>` | no | max items 32 |
 | `body.visibility` | `"open" \| "private" \| null` | no |  |
@@ -2983,6 +2984,20 @@ One Work channel as the room stores it.
 | `system` | `boolean \| null` | no | True for a built-in channel (`#work`, `#signals`) |
 | `visibility` | `string \| null` | no | `open` (self-serve joinable) or `private` (invite only) |
 
+<a id="type-workchannelicon"></a>
+
+### `WorkChannelIcon`
+
+A channel's icon: a glyph on a color, an emoji, or an uploaded image. `glyph` and `color` are ids from the client's curated sets, never raw CSS or SVG, so nothing a member stores can inject markup or styles into another member's sidebar. An image is a Work attachment id, never a URL: readability is re-checked on every read (`readable_attachment_ids`).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | `"glyph" \| "emoji" \| "image"` | yes |  |
+| `attachmentId` | `string \| null` | no | pattern `^[A-Za-z0-9-]{1,64}$` |
+| `color` | `string \| null` | no | pattern `^[a-z0-9-]{1,32}$` |
+| `emoji` | `string \| null` | no | min length 1, max length 16 |
+| `glyph` | `string \| null` | no | pattern `^[a-z0-9-]{1,40}$` |
+
 <a id="type-workevent"></a>
 
 ### `WorkEvent`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graph8/sdk",
-  "version": "0.295.2",
+  "version": "0.302.0",
   "description": "graph8 SDK - CRM, enrichment, sequences, campaigns, and tracking for B2B",
   "license": "MIT",
   "author": "graph8 <support@graph8.com> (https://graph8.com)",