@graph8/sdk 0.12.0 → 0.13.0

package/dist/react.d.ts

@@ -580,6 +580,29 @@ interface IntentCompany {
     visit_count: number;
     last_seen: string | null;
 }
+/** One company row from `intent.urlCompanies()`. Richer than {@link IntentCompany},
+ * which describes the keyword-companies surface. */
+interface IntentUrlCompany {
+    company_id: number | null;
+    name: string | null;
+    domain: string | null;
+    industry: string | null;
+    employee_count: number | null;
+    logo_url: string | null;
+    audience: string;
+    visit_count: number;
+    contacts_seen: number;
+    last_seen: string | null;
+}
+/** Response of `intent.urlCompanies()`. This endpoint returns a bare aggregate,
+ * not the `{ data }` envelope the rest of the Developer API uses. */
+interface IntentUrlCompaniesResponse {
+    url: string;
+    total_companies: number;
+    b2b_count: number;
+    b2c_count: number;
+    companies: IntentUrlCompany[];
+}
 interface IntentContact {
     contact_id: number | null;
     email: string | null;
@@ -614,7 +637,7 @@ interface IntentStats {
  *   POST   /api/v1/intent/pages/visitors
  *   POST   /api/v1/intent/pages/contacts
  *   POST   /api/v1/intent/pages/visitor-counts
- *   POST   /intent-search/url-companies          (note: bare host, no /api/v1 prefix)
+ *   POST   /api/v1/intent/url-companies
  */
 declare const createIntentClient: (apiKey: string, apiUrl?: string) => {
     /** Org-level intent stats (totals over the last 30 days). */
@@ -697,16 +720,24 @@ declare const createIntentClient: (apiKey: string, apiUrl?: string) => {
     /**
      * Find companies whose users visited a specific URL (intent search).
      *
-     * Note: this endpoint lives at the bare host (no `/api/v1` prefix), unlike the rest
-     * of the intent surface — we call it directly here instead of through the shared `post()` helper.
+     * Previously posted to the bare-host `/intent-search/url-companies`, bypassing
+     * the shared `post()` helper. That route is JWT-only, so this method could
+     * never actually work with an API key. It now goes through
+     * `/api/v1/intent/url-companies` like the rest of the intent surface (g8 issue
+     * #16536).
+     *
+     * Returns a bare aggregate, NOT the `{ data }` envelope — the previous
+     * `{ data: IntentCompany[] }` signature never matched what the API sends.
+     *
+     * `date_from` / `date_to` are accepted for backwards compatibility but have
+     * never been read by this endpoint; use `days` to set the lookback window.
      */
     urlCompanies(url: string, params?: {
         limit?: number;
+        days?: number;
         date_from?: string;
         date_to?: string;
-    }): Promise<{
-        data: IntentCompany[];
-    }>;
+    }): Promise<IntentUrlCompaniesResponse>;
 };
 
 type SkillType = "llm" | "api";
@@ -1555,14 +1586,28 @@ interface DealCreateParams {
      */
     company_id?: number;
     description?: string;
+    /**
+     * Monetary value. Required (HTTP 400, marker `amount_required_for_won_stage`)
+     * when creating directly in a Closed Won stage; 0 is a valid amount.
+     */
     amount?: number;
     /** Default: "USD". */
     currency?: string;
-    /** Stage ID from the org's pipelines. Defaults to first stage of default pipeline if omitted. */
+    /**
+     * Stage ID from the org's pipelines. Must exist and belong to `pipeline_id`
+     * when both are sent (HTTP 422 otherwise). Defaults to the default
+     * pipeline's first non-closed stage if omitted. Creating directly in a
+     * closed stage triggers the closed-stage rules (HTTP 400 with marker
+     * `close_date_required_for_won_stage` / `close_date_required_for_lost_stage`
+     * / `amount_required_for_won_stage` / `owner_required_for_closed_stage`).
+     */
     stage_id?: string;
-    /** Pipeline ID. Defaults to org's default pipeline if omitted. */
+    /** Pipeline ID. Must exist (HTTP 422 otherwise). Defaults to org's default pipeline if omitted. */
     pipeline_id?: string;
-    /** ISO 8601 close date. */
+    /**
+     * ISO 8601 close date. Required when creating directly in a Closed Won or
+     * Closed Lost stage; past dates are allowed (backdating is supported).
+     */
     close_date?: string;
     /**
      * Set true to create a deal even if one already exists for the company.
@@ -1575,10 +1620,28 @@ interface DealUpdateParams {
     description?: string;
     amount?: number;
     currency?: string;
+    /**
+     * New stage ID. Must be an existing stage in the deal's pipeline (HTTP 422
+     * otherwise). Moving a deal INTO a Closed Won stage requires an effective
+     * close_date AND amount; Closed Lost requires an effective close_date;
+     * either requires an owner ("effective" = the value in this call, else the
+     * deal's existing value). Violations return HTTP 400 with a marker-prefixed
+     * detail: `close_date_required_for_won_stage`,
+     * `close_date_required_for_lost_stage`, `amount_required_for_won_stage`,
+     * `owner_required_for_closed_stage`. Re-submitting the deal's current stage
+     * is never gated.
+     */
     stage_id?: string;
-    /** ISO 8601 close date. */
-    close_date?: string;
-    /** Reassign the deal owner (user id or email). Pass null to clear. */
+    /**
+     * ISO 8601 close date. Explicit null clears it, except on a deal sitting in
+     * a closed stage (HTTP 400, closed-stage markers above).
+     */
+    close_date?: string | null;
+    /**
+     * Reassign the deal owner (user id or email). Pass null to clear, except on
+     * a deal sitting in a closed stage (HTTP 400, marker
+     * `owner_required_for_closed_stage`).
+     */
     owner_id?: string | null;
     /**
      * mashup_contact_ids to link. Must belong to the deal's company (if the deal
@@ -1678,6 +1741,296 @@ declare const createDealsClient: (apiKey: string, apiUrl?: string) => {
     }>;
 };
 
+/** A custom object type in your workspace — a record type you define. */
+interface CustomObject {
+    /** Stable API slug, e.g. `invoices`. */
+    slug: string;
+    singular_noun: string;
+    plural_noun: string;
+    /** True for object types graph8 ships; system objects cannot be deleted. */
+    is_system: boolean;
+    is_archived: boolean;
+}
+/**
+ * One attribute on a custom object, and the rules its values must satisfy.
+ *
+ * `attribute_type` is one of 16 supported types and decides how a value is
+ * validated and canonicalized: `text`, `number`, `currency`, `date`,
+ * `timestamp`, `checkbox`, `select`, `status`, `email_address`, `phone_number`,
+ * `domain`, `location`, `personal_name`, `record_reference`, `rating`,
+ * `actor_reference`.
+ */
+interface CustomObjectAttribute {
+    slug: string;
+    attribute_type: string;
+    is_required: boolean;
+    /** No two ACTIVE records may hold the same value. A collision returns 409. */
+    is_unique: boolean;
+    is_multiselect: boolean;
+    /** Type-specific configuration, e.g. the allowed options for a `select`. */
+    config: Record<string, unknown>;
+}
+/** One record, with its currently active attribute values. */
+interface CustomObjectRecord {
+    id: string;
+    object_slug: string;
+    /**
+     * Values keyed by attribute slug. Untyped by necessity — the valid keys come
+     * from YOUR attribute definitions at runtime, so call `listAttributes` for the
+     * schema. Saying `any` here would imply the shape was considered and found to
+     * be free.
+     */
+    values: Record<string, unknown>;
+    is_archived: boolean;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/** One generation of one attribute's value. */
+interface CustomObjectHistoryEntry {
+    attribute: string;
+    value: unknown;
+    active_from: string | null;
+    /** Null means this value is still in force. */
+    active_until: string | null;
+    actor_id: string | null;
+}
+interface CustomObjectHistory {
+    record_id: string;
+    entries: CustomObjectHistoryEntry[];
+}
+interface ListRecordsParams {
+    page?: number;
+    /** 1-200, default 50. */
+    limit?: number;
+    /** Opaque cursor from a prior response. Takes precedence over `page`. */
+    cursor?: string;
+}
+/**
+ * Pagination envelope for record listings.
+ *
+ * Named distinctly rather than `PaginationMeta`: `deals.ts` and `quotes.ts` each
+ * already declare their own structurally identical `PaginationMeta`, and one of
+ * them is re-exported from `index.ts` — so a third with that name is a
+ * `TS2300: Duplicate identifier` at the package's export site. Consolidating the
+ * three into one shared type is worth doing and is not this change.
+ */
+interface ObjectPagination {
+    page: number;
+    limit: number;
+    total: number;
+    has_next: boolean;
+    next_cursor: string | null;
+}
+/**
+ * Custom Objects API — your own record types, their schema, and their records (M6-3).
+ * Requires an API key (server-side). On the hardened HTTP core: throws a typed
+ * `G8Error` on failure and retries transient errors.
+ *
+ * PREVIEW AND GATED. Every endpoint returns 403 `app_not_enabled` until the
+ * custom-objects surface is switched on for the platform. It is off by default,
+ * so a call fails fast rather than returning an empty list that reads as "you
+ * have no objects".
+ *
+ * HOW THIS DIFFERS FROM `g8.fields`. A FIELD adds a column to an existing
+ * contact or company. A CUSTOM OBJECT is a whole new record type with its own
+ * attributes and its own records. Use fields to extend a contact; use custom
+ * objects to model an invoice, a shipment, or a subscription.
+ *
+ * THREE BEHAVIOURS WORTH KNOWING BEFORE YOU WRITE
+ *
+ *   1. An unknown field is REJECTED (422), not ignored. A typo does not silently
+ *      lose your data, and the response lists every problem at once so a payload
+ *      with three mistakes takes one round trip to fix.
+ *   2. `update` is a PARTIAL write. Attributes you omit are left alone; sending
+ *      an explicit `null` CLEARS one. The two are deliberately different.
+ *   3. `archive` does not destroy anything. The record leaves listings, stays
+ *      readable by id, and keeps its history.
+ *
+ * Backed by:
+ *   GET    /api/v1/objects
+ *   GET    /api/v1/objects/{slug}
+ *   GET    /api/v1/objects/{slug}/attributes
+ *   GET    /api/v1/objects/{slug}/records
+ *   POST   /api/v1/objects/{slug}/records
+ *   GET    /api/v1/objects/{slug}/records/{id}
+ *   PATCH  /api/v1/objects/{slug}/records/{id}
+ *   DELETE /api/v1/objects/{slug}/records/{id}
+ *   GET    /api/v1/objects/{slug}/records/{id}/history
+ */
+declare const createObjectsClient: (apiKey: string, apiUrl?: string) => {
+    /** List the custom object types in your workspace. */
+    list(): Promise<{
+        data: CustomObject[];
+    }>;
+    /** Fetch one object type by slug. */
+    get(objectSlug: string): Promise<CustomObject>;
+    /** The object's attributes — the schema its records must satisfy. */
+    listAttributes(objectSlug: string): Promise<{
+        data: CustomObjectAttribute[];
+    }>;
+    /** Paginated records with their current values. Archived records are excluded. */
+    listRecords(objectSlug: string, params?: ListRecordsParams): Promise<{
+        data: CustomObjectRecord[];
+        pagination?: ObjectPagination;
+    }>;
+    /**
+     * Create a record. Every field is validated against the object's attributes;
+     * an unknown one is a 422 listing every problem at once, and a collision on a
+     * unique attribute is a 409.
+     */
+    createRecord(objectSlug: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+    /** Fetch one record with its currently active values. */
+    getRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+    /**
+     * Update a record. PARTIAL: only the attributes you send are touched, so
+     * required attributes you omit are left alone rather than reported missing.
+     * Sending an explicit `null` CLEARS that attribute.
+     *
+     * Values are versioned rather than overwritten, so the previous value stays
+     * readable through `history`.
+     */
+    updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+    /**
+     * Archive a record. It leaves listings, stays readable by id, and keeps its
+     * history and associations. Nothing is destroyed.
+     */
+    archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+    /**
+     * A record's value timeline, newest first. An entry whose `active_until` is
+     * null is the value currently in force.
+     */
+    history(objectSlug: string, recordId: string, limit?: number): Promise<CustomObjectHistory>;
+};
+
+/**
+ * App lifecycle. `draft` serves no traffic; `published` is live; `suspended` is a
+ * platform action and cannot be set through this client; `archived` is retired.
+ *
+ * `active` is the pre-D12c spelling of `published` and is still accepted on write
+ * by the backend, so an older caller keeps working. Prefer `published`.
+ */
+type AppStatus = "draft" | "published" | "suspended" | "archived";
+/** An app you build on graph8, which your customers install into their workspace. */
+interface App {
+    app_id: string;
+    builder_org_id: string;
+    /** Stable identifier, unique within your organization — not globally. */
+    slug: string;
+    name: string;
+    status: string;
+    /** https-only origins a BROWSER app token may be presented from. */
+    registered_origins: string[];
+    default_hostname: string | null;
+    created_at: string | null;
+    archived_at: string | null;
+}
+/** One client organization's installation of your app. */
+interface AppInstallation {
+    install_id: string;
+    app_id: string;
+    client_org_id: string;
+    status: string;
+    consented_scopes: string[];
+    created_at: string | null;
+    revoked_at: string | null;
+}
+/** Credits your app consumed in one calendar month. */
+interface AppUsageSummary {
+    app_id: string;
+    /** Calendar month, `YYYY-MM`. */
+    period: string;
+    total_credits: number;
+    event_count: number;
+    /**
+     * Credits per CLIENT org — whose data was touched, not who paid. You pay for
+     * all of them, so a breakdown keyed on the payer would collapse into one row.
+     */
+    per_client_credits: Record<string, number>;
+}
+/** A hard credit cap. `null` from `getLimit` means uncapped. */
+interface AppLimit {
+    app_id: string;
+    window: string;
+    credit_cap: number;
+    created_at: string | null;
+}
+interface AppCreateParams {
+    name: string;
+    /** Unique within your organization. Lowercased on write. */
+    slug: string;
+    /**
+     * https-only origins a browser app token may be presented from. An `http://`
+     * origin is rejected at registration — a bearer token sent over plain http is
+     * a token disclosed to the network.
+     */
+    registered_origins?: string[];
+}
+/**
+ * Apps API — manage the apps you build on graph8 (M6). Requires an API key
+ * (server-side). On the hardened HTTP core: throws a typed `G8Error` on failure
+ * and retries transient errors.
+ *
+ * PREVIEW AND GATED. Every endpoint returns 403 `builder_not_allowlisted` unless
+ * the platform is enabled AND your organization is on the builder allowlist.
+ * Both are off by default, so a call fails fast and loudly rather than returning
+ * an empty list that looks like "you have no apps".
+ *
+ * A note on 404s: an app id belonging to ANOTHER organization returns 404, not
+ * 403 — the two are deliberately indistinguishable so app ids cannot be
+ * enumerated by guessing.
+ *
+ * Backed by:
+ *   GET  /api/v1/apps                        — list your apps
+ *   POST /api/v1/apps                        — create one (starts in `draft`)
+ *   GET  /api/v1/apps/{app_id}               — fetch one
+ *   POST /api/v1/apps/{app_id}/status        — move it through its lifecycle
+ *   GET  /api/v1/apps/{app_id}/installs      — who installed it, and their consent
+ *   GET  /api/v1/apps/{app_id}/usage         — credits consumed in a month
+ *   GET  /api/v1/apps/{app_id}/limit         — the hard cap, or null
+ */
+declare const createAppsClient: (apiKey: string, apiUrl?: string) => {
+    /** List your organization's apps, newest first. */
+    list(): Promise<{
+        data: App[];
+    }>;
+    /** Fetch one of your apps. Throws `G8Error` (404) if it is not yours. */
+    get(appId: string): Promise<App>;
+    /**
+     * Create an app. It starts in `draft` and serves no traffic until published.
+     * Throws `G8Error` (409) when the slug is already taken in your org.
+     */
+    create(params: AppCreateParams): Promise<App>;
+    /**
+     * Move an app through its lifecycle: `draft` → `published` → `archived`.
+     *
+     * `suspended` is excluded from the parameter type on purpose: it is the
+     * platform's kill switch for an abusive app, the backend refuses it with a
+     * 403, and a builder who could set it could also unset it.
+     */
+    setStatus(appId: string, status: Exclude<AppStatus, "suspended">): Promise<App>;
+    /**
+     * The client organizations that installed this app, and their consent state.
+     * Includes `pending` and `revoked` installs — if your app cannot reach a
+     * tenant, this is where you see why.
+     */
+    listInstalls(appId: string): Promise<{
+        data: AppInstallation[];
+    }>;
+    /**
+     * Credits this app consumed in a calendar month, broken down per client org.
+     * Defaults to the current month. A month with no usage returns zeroes, not a
+     * 404 — "nothing happened" is an answer.
+     */
+    usage(appId: string, period?: string): Promise<AppUsageSummary>;
+    /**
+     * This app's hard credit cap, or `null` when it is uncapped.
+     *
+     * `null` is the real answer, not an empty object: there is no "unlimited"
+     * sentinel, so an accidental zero can never read as "no limit".
+     */
+    getLimit(appId: string): Promise<AppLimit | null>;
+};
+
 /** A field (column) definition on contacts or companies — base or custom. */
 interface Field {
     id: number | null;
@@ -3132,6 +3485,8 @@ declare const useG8: () => {
         _notes: ReturnType<typeof createNotesClient> | null;
         _tasks: ReturnType<typeof createTasksClient> | null;
         _fields: ReturnType<typeof createFieldsClient> | null;
+        _apps: ReturnType<typeof createAppsClient> | null;
+        _objects: ReturnType<typeof createObjectsClient> | null;
         _deals: ReturnType<typeof createDealsClient> | null;
         _inbox: ReturnType<typeof createInboxClient> | null;
         _quotes: ReturnType<typeof createQuotesClient> | null;
@@ -3391,6 +3746,37 @@ declare const useG8: () => {
                 };
             }>;
         };
+        get apps(): {
+            list(): Promise<{
+                data: App[];
+            }>;
+            get(appId: string): Promise<App>;
+            create(params: AppCreateParams): Promise<App>;
+            setStatus(appId: string, status: Exclude<AppStatus, "suspended">): Promise<App>;
+            listInstalls(appId: string): Promise<{
+                data: AppInstallation[];
+            }>;
+            usage(appId: string, period?: string): Promise<AppUsageSummary>;
+            getLimit(appId: string): Promise<AppLimit | null>;
+        };
+        get objects(): {
+            list(): Promise<{
+                data: CustomObject[];
+            }>;
+            get(objectSlug: string): Promise<CustomObject>;
+            listAttributes(objectSlug: string): Promise<{
+                data: CustomObjectAttribute[];
+            }>;
+            listRecords(objectSlug: string, params?: ListRecordsParams): Promise<{
+                data: CustomObjectRecord[];
+                pagination?: ObjectPagination;
+            }>;
+            createRecord(objectSlug: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+            getRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+            updateRecord(objectSlug: string, recordId: string, values: Record<string, unknown>): Promise<CustomObjectRecord>;
+            archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+            history(objectSlug: string, recordId: string, limit?: number): Promise<CustomObjectHistory>;
+        };
         get deals(): {
             pipelines(): Promise<{
                 data: Pipeline[];
@@ -3719,11 +4105,10 @@ declare const useG8: () => {
             }>;
             urlCompanies(url: string, params?: {
                 limit?: number;
+                days?: number;
                 date_from?: string;
                 date_to?: string;
-            }): Promise<{
-                data: IntentCompany[];
-            }>;
+            }): Promise<IntentUrlCompaniesResponse>;
         };
         get studio(): {
             globalContext(params?: {