@graph8/sdk 0.12.2 → 0.13.1

package/dist/react.d.mts

@@ -1741,6 +1741,309 @@ 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;
+    /** Apply a non-null default to omitted create fields, never PATCH. Absent on older servers. */
+    is_default_value_enabled?: boolean;
+    /** Configured default; validated like an explicit value when enabled. */
+    default_value?: unknown;
+    /** 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;
+    /** Revision for conditional updates; absent on older servers. */
+    revision?: number;
+    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.
+ *
+ * Access requires an authenticated credential with the applicable object scope.
+ *
+ * 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 an optional attribute. Required attributes
+ *      cannot be cleared with `null` or an empty multivalue list (422).
+ *   3. `archive` does not destroy anything. The record leaves listings, stays
+ *      readable by id, and keeps its history.
+ *
+ * Record references must resolve to an active record of `config.target_object`
+ * within the same organization and app. Unavailable targets return a 422 with
+ * `invalid_reference` in the field error's `reason`, without disclosing whether
+ * a target exists outside the caller's scope.
+ *
+ * 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>, options?: {
+        expectedRevision?: number;
+    }): 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>;
+    /** Restore archived values under current constraints. Conflicts leave the record archived. */
+    restoreRecord(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;
@@ -3195,6 +3498,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;
@@ -3454,6 +3759,40 @@ 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>, options?: {
+                expectedRevision?: number;
+            }): Promise<CustomObjectRecord>;
+            archiveRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+            restoreRecord(objectSlug: string, recordId: string): Promise<CustomObjectRecord>;
+            history(objectSlug: string, recordId: string, limit?: number): Promise<CustomObjectHistory>;
+        };
         get deals(): {
             pipelines(): Promise<{
                 data: Pipeline[];