@graph8/sdk 0.251.0 → 0.260.0

package/dist/types/appTokens.d.ts

@@ -0,0 +1,125 @@
+/**
+ * App-platform token exchange + refresh core (M6-9).
+ *
+ * The hosted-app clients never carry a permanent org API key. Instead they mint
+ * SHORT-LIVED app tokens by EXCHANGING a longer-lived credential, and refresh
+ * them on/near expiry:
+ *
+ *   - browser apps exchange the caller's PropelAuth login at
+ *     `POST /api/v1/app-sessions/exchange` (identity is derived server-side from
+ *     the validated principal — the body only names the target app + scopes);
+ *   - hosted backends exchange service client-credentials at
+ *     `POST /api/v1/service-token`.
+ *
+ * Both endpoints answer with the reused `ApiResponse` envelope wrapping a
+ * `TokenResponse` (see developer_api/app_platform/app_tokens/dtos.py). This
+ * module owns:
+ *
+ *   - `AppTokenResponse` — the minted-token payload shape (frozen wire contract);
+ *   - `createTokenManager` — caches a token, refreshes it on/near expiry, and
+ *     de-dupes concurrent refreshes into one in-flight exchange;
+ *   - `createAppRequester` — binds the managed token onto the hardened
+ *     `request()` core (typed `G8Error`, retries, idempotency, pagination),
+ *     attaching `Authorization: Bearer <app-token>` (plus any static header such
+ *     as a service client's `X-Target-Org-Id`) and refreshing once on a 401.
+ *
+ * The backend app-token API is INERT/unmounted today (behind a deny-by-default
+ * flag), so these paths are exercised against mocked HTTP, never a live server.
+ */
+export declare const DEFAULT_APP_API = "https://be.graph8.com";
+/** The minted app token + the non-secret metadata a client reads back.
+ *  Mirrors `TokenResponse` in developer_api/app_platform/app_tokens/dtos.py. */
+export interface AppTokenResponse {
+    /** The signed app JWT (attach as `Authorization: Bearer <access_token>`). */
+    access_token: string;
+    /** Always "Bearer". */
+    token_type: string;
+    /** Lifetime in seconds from issuance. */
+    expires_in: number;
+    /** The distinct-per-app, per-environment audience. */
+    audience: string;
+    /** App the token is bound to (dapp_-prefixed). */
+    app_id: string;
+    /** Signing key id (matches a JWKS entry). */
+    kid: string;
+}
+/** Per-request options accepted by an {@link AppRequest}. A subset of the
+ *  hardened core's `RequestOptions` — auth (the app token) and the injected
+ *  fetch/sleep seams are bound by the requester, not passed per call. */
+export interface AppRequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    /** Sent as `Idempotency-Key` for safe POST/PATCH retries. */
+    idempotencyKey?: string;
+    /** Max retry attempts on 429/5xx/network (default 2). */
+    maxRetries?: number;
+    /** Base backoff in ms (default 200). */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+}
+/** A token-bound request function: same ergonomics as the raw `request()` core
+ *  minus the credential, which the token manager supplies. */
+export type AppRequest = <T = unknown>(path: string, opts?: AppRequestOptions) => Promise<T>;
+/** Caches + refreshes one app token. */
+export interface TokenManager {
+    /** Return a valid token, refreshing on/near expiry. `force` refreshes now. */
+    getToken(force?: boolean): Promise<string>;
+    /** Current token expiry as an epoch-ms timestamp (0 before the first mint). */
+    expiresAt(): number;
+}
+/**
+ * Build a token manager over a `refresh` exchange.
+ *
+ * Freshness rule: a cached token is reused until it is within `refreshSkewMs`
+ * of expiry, then a refresh is triggered. Concurrent callers during a refresh
+ * share ONE in-flight exchange (no stampede). `now` is injectable for tests.
+ */
+export declare function createTokenManager(args: {
+    refresh: () => Promise<AppTokenResponse>;
+    now?: () => number;
+    refreshSkewMs?: number;
+}): TokenManager;
+/**
+ * Bind a {@link TokenManager} onto the hardened `request()` core.
+ *
+ * Every call fetches the current token, attaches `Authorization: Bearer …`
+ * (plus any `extraHeaders`, e.g. a service client's `X-Target-Org-Id`), and
+ * reuses all of the core's typed errors / retries / idempotency. On a 401 —
+ * a token revoked or gone stale mid-window — it force-refreshes ONCE and retries.
+ */
+export declare function createAppRequester(args: {
+    baseUrl: string;
+    tokens: TokenManager;
+    extraHeaders?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): AppRequest;
+/**
+ * Exchange the caller's PropelAuth token for a short-lived BROWSER app token.
+ * `POST /api/v1/app-sessions/exchange` (body = target app + scopes only;
+ * identity/role/tenant are derived server-side from the validated principal).
+ */
+export declare function exchangeBrowserToken(args: {
+    baseUrl: string;
+    appId: string;
+    scopes?: string[];
+    getPropelAuthToken: () => string | Promise<string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+/**
+ * Exchange service client-credentials for a SERVICE app token.
+ * `POST /api/v1/service-token` — credentials travel in the body; this endpoint
+ * has no bearer auth, so no `Authorization` is sent on the exchange itself.
+ */
+export declare function exchangeServiceToken(args: {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+    ttlSeconds?: number;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;

package/dist/types/apps.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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`.
+ */
+export type AppStatus = "draft" | "published" | "suspended" | "archived";
+/** Install / consent lifecycle for one client org. */
+export type InstallStatus = "pending" | "consented" | "revoked" | "suspended" | "expired";
+/** An app you build on graph8, which your customers install into their workspace. */
+export 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. */
+export 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. */
+export 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. */
+export interface AppLimit {
+    app_id: string;
+    window: string;
+    credit_cap: number;
+    created_at: string | null;
+}
+export 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
+ */
+export 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>;
+};

package/dist/types/audiences.d.ts

@@ -0,0 +1,88 @@
+/** Ad platform an audience can sync to. */
+export type AudienceSyncPlatform = "meta" | "linkedin" | "google" | "x";
+/** Sync mode: full mirror, or only ever add members. */
+export type AudienceSyncMode = "mirror" | "append_only";
+export interface AudienceSync {
+    id: number;
+    audience_id: number;
+    platform: string;
+    platform_audience_name: string | null;
+    mode: string;
+    refresh_cadence_hours: number;
+    is_active: boolean;
+    status: string | null;
+    last_sync_at: string | null;
+    created_at: string | null;
+}
+export interface AudienceSyncCreateParams {
+    /** Audience list ID to sync. */
+    audience_id: number;
+    platform: AudienceSyncPlatform;
+    platform_audience_name?: string;
+    /** Default "mirror". */
+    mode?: AudienceSyncMode;
+    /** Refresh cadence in hours (0-720; default 24). */
+    refresh_cadence_hours?: number;
+    /** Platform-specific config (OAuth creds, ad-account ids, etc.). */
+    platform_config?: Record<string, unknown>;
+    /** Audience list IDs whose members should be suppressed from the sync. */
+    suppression_list_ids?: number[];
+}
+export interface AudienceSyncUpdateParams {
+    mode?: AudienceSyncMode;
+    refresh_cadence_hours?: number;
+    is_active?: boolean;
+    suppression_list_ids?: number[];
+}
+export interface AudienceSyncRun {
+    id: number;
+    started_at: string | null;
+    finished_at: string | null;
+    status: string | null;
+    members_added: number | null;
+    members_removed: number | null;
+    total_members: number | null;
+    error_message: string | null;
+}
+export interface AudienceSyncError {
+    id: number;
+    started_at: string | null;
+    error_message: string | null;
+    details: Record<string, unknown> | null;
+}
+/**
+ * Audiences API — sync an audience list to ad platforms (Meta, LinkedIn,
+ * Google, X). Requires API key (server-side). Built on the hardened HTTP core,
+ * so every method throws a typed `G8Error` on failure and retries transient
+ * 429/5xx/network errors.
+ *
+ * Backed by `/api/v1/audience-syncs`.
+ */
+export declare const createAudiencesClient: (apiKey: string, apiUrl?: string) => {
+    /** List all audience syncs for the organization. */
+    list(): Promise<{
+        data: AudienceSync[];
+    }>;
+    /** Create a new audience sync to an ad platform. */
+    create(params: AudienceSyncCreateParams): Promise<AudienceSync>;
+    /** Get a single audience sync by ID. */
+    get(configId: number): Promise<AudienceSync>;
+    /** Update an audience sync (partial). */
+    update(configId: number, fields: AudienceSyncUpdateParams): Promise<AudienceSync>;
+    /** Delete an audience sync. */
+    delete(configId: number): Promise<{
+        data: Record<string, unknown>;
+    }>;
+    /** Trigger an immediate sync run for a config. */
+    trigger(configId: number): Promise<{
+        data: Record<string, unknown>;
+    }>;
+    /** List recent sync runs for a config (most recent first). */
+    runs(configId: number): Promise<{
+        data: AudienceSyncRun[];
+    }>;
+    /** List recent sync errors for a config. */
+    errors(configId: number): Promise<{
+        data: AudienceSyncError[];
+    }>;
+};

package/dist/types/calendar.d.ts

@@ -0,0 +1,55 @@
+export interface CalendarConfig {
+    /** Event type slug (e.g. "demo-30min") */
+    eventType: string;
+    /** Username of the host */
+    username: string;
+    /** Pre-fill attendee info */
+    prefill?: {
+        name?: string;
+        email?: string;
+        notes?: string;
+    };
+}
+export interface TimeSlot {
+    start: string;
+    end: string;
+    available: boolean;
+}
+export interface Booking {
+    uid: string;
+    confirmation_url: string;
+    start_time: string;
+    end_time: string;
+}
+export interface BookingRequest {
+    event_type_id: number;
+    slot: string;
+    attendee: {
+        name: string;
+        email: string;
+        notes?: string;
+    };
+}
+type CalendarEvent = "booked" | "cancelled" | "slot_selected";
+type CalendarCallback = (data: Record<string, unknown>) => void;
+/**
+ * Calendar and booking - show scheduling widgets, get slots, book meetings.
+ *
+ * Public endpoints - no API key needed.
+ */
+export declare const createCalendarClient: (apiUrl?: string) => {
+    /** Show a booking modal overlay. */
+    show(config: CalendarConfig): void;
+    /** Embed booking widget inline in a container element. */
+    embed(selector: string, config: CalendarConfig): void;
+    /** Get available time slots for an event type. */
+    slots(username: string, eventSlug: string, range: {
+        start: string;
+        end: string;
+    }): Promise<TimeSlot[]>;
+    /** Book a meeting programmatically. */
+    book(request: BookingRequest): Promise<Booking | null>;
+    /** Listen for calendar events. */
+    on(event: CalendarEvent, callback: CalendarCallback): void;
+};
+export {};

package/dist/types/campaigns.d.ts

@@ -0,0 +1,61 @@
+export interface Campaign {
+    id: string;
+    name: string;
+    slug: string;
+    status: string;
+    category: string | null;
+    goal: string | null;
+    target_persona: string | null;
+}
+export interface CampaignCreateConfig {
+    name: string;
+    category?: string;
+    brief?: string;
+    core_concept?: string;
+    primary_hook?: string;
+    target_persona?: string;
+    goal?: string;
+}
+export interface CampaignLaunchExecution {
+    status: string;
+    contacts_total?: number;
+    contacts_scheduled?: number;
+    contacts_queued?: number;
+    job_id?: string;
+    polling_url?: string;
+    orchestrator_version?: string;
+}
+export interface CampaignLaunchResult {
+    status: string;
+    campaign_id: string;
+    sequence_id: string;
+    sequence_name: string;
+    steps_created: number;
+    link_id: string;
+    warnings: string[];
+    channels_attached: Array<{
+        mailbox_id: number;
+        email: string;
+        channel_type: string;
+        auto_picked: boolean;
+    }>;
+    agent_assigned: {
+        textual_agent_name: string | null;
+        voice_agent_name: string | null;
+    };
+    schedule_id: string | null;
+    appointment_id: number | null;
+    execution: CampaignLaunchExecution;
+    message: string;
+}
+/**
+ * Campaigns - create, manage, launch campaigns. Requires API key (server-side).
+ * On the hardened HTTP core: throws a typed `G8Error` on failure and retries
+ * transient errors.
+ */
+export declare const createCampaignsClient: (apiKey: string, apiUrl?: string) => {
+    list(page?: number, limit?: number): Promise<Campaign[]>;
+    get(campaignId: string): Promise<Campaign>;
+    create(config: CampaignCreateConfig): Promise<Campaign>;
+    launch(campaignId: string): Promise<CampaignLaunchResult>;
+};

package/dist/types/chat.d.ts

@@ -0,0 +1,35 @@
+export interface ChatConfig {
+    /** Agent ID to connect to */
+    agentId?: string;
+    /** Pre-filled first message */
+    message?: string;
+    /** Widget position */
+    position?: "bottom-right" | "bottom-left";
+    /** Widget theme */
+    theme?: "light" | "dark" | "auto";
+    /** Custom greeting */
+    greeting?: string;
+    /** Custom avatar URL */
+    avatar?: string;
+}
+type ChatEvent = "message" | "human_transfer" | "open" | "close" | "error";
+type ChatCallback = (data: Record<string, unknown>) => void;
+/**
+ * Webchat - live chat + AI chat embedded in any app.
+ *
+ * Uses WebSocket connection to the voice/chat agent backend.
+ * Public - no API key needed (org/agent IDs are in the config).
+ */
+export declare const createChatClient: (writeKey: string, apiUrl?: string) => {
+    /** Open the chat widget. */
+    open(config?: ChatConfig): void;
+    /** Send a message. */
+    send(message: string): void;
+    /** Listen for chat events. */
+    on(event: ChatEvent, callback: ChatCallback): void;
+    /** Configure the chat appearance. */
+    configure(config: Partial<ChatConfig>): void;
+    /** Close the chat widget. */
+    close(): void;
+};
+export {};

package/dist/types/cli.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `@graph8/sdk` command line (the package's `bin`), run with npx:
+ *
+ *   npx @graph8/sdk init-agent [--claude] [--codex] [--cursor] [--dry-run]
+ *
+ * Node only. Built as a separate entry (dist/cli.js), so nothing here reaches
+ * the browser bundle or the package's main exports.
+ */
+export interface CliIO {
+    cwd: string;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+export declare function runCli(argv: string[], io: CliIO): number;

package/dist/types/companies.d.ts

@@ -0,0 +1,123 @@
+export interface Company {
+    id: number;
+    name: string | null;
+    domain: string | null;
+    industry: string | null;
+    employee_count: number | null;
+    revenue: number | null;
+    founded_year: number | null;
+    description: string | null;
+    linkedin_url: string | null;
+    country: string | null;
+    state: string | null;
+    city: string | null;
+}
+export interface CompanyListParams {
+    page?: number;
+    limit?: number;
+    domain?: string;
+    industry?: string;
+    name?: string;
+    country?: string;
+}
+export interface CompanyUpdateParams {
+    name?: string;
+    domain?: string;
+    industry?: string;
+    description?: string;
+    linkedin_url?: string;
+    country?: string;
+    state?: string;
+    city?: string;
+}
+export interface CompanyContact {
+    id: number;
+    first_name: string | null;
+    last_name: string | null;
+    work_email: string | null;
+    job_title: string | null;
+}
+/** A column definition on companies (base or custom). */
+export interface CompanyColumn {
+    id: number | null;
+    title: string;
+    data_type: string;
+    name: string | null;
+    /** Stringified list_id when list-scoped, otherwise null/empty for global. */
+    object_id: string | null;
+    is_global: boolean;
+}
+export interface CompanyCreateParams {
+    /**
+     * Company domain, e.g. "acme.com". REQUIRED — it drives dedup: an existing
+     * company with the same domain is reused rather than duplicated.
+     */
+    domain: string;
+    name?: string;
+    website?: string;
+    phone?: string;
+    address?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    zip?: string;
+    industry?: string;
+    /** Sent as a string by the API (e.g. "51-200"), not a number. */
+    employee_count?: string;
+    linkedin_url?: string;
+    /** Optional list to add the company to after creation. */
+    list_id?: number;
+}
+export interface CompanyCreateResult {
+    status: string;
+    /** mashup_companies.id — pass to contacts.update({company_id}) or use on a deal. */
+    company_id: number | null;
+    /** True when an existing company with the same domain was reused. */
+    merged: boolean;
+}
+export interface CompanyColumnCreateParams {
+    title: string;
+    /** Email of the user creating the column. Required by the backend (audit). */
+    created_by: string;
+    /** "text" (default) — additional types may be added later. */
+    data_type?: string;
+    /** If set, the column is list-specific. Omit for org-wide global column. */
+    list_id?: number;
+}
+/**
+ * Companies API - search and manage CRM companies. Requires API key (server-side).
+ */
+export declare const createCompaniesClient: (apiKey: string, apiUrl?: string) => {
+    /**
+     * Create a company. `domain` is required and drives dedup — an existing
+     * company with the same domain is reused (`merged: true`) rather than
+     * duplicated. Routes to the same handler the in-app "add company" flow uses.
+     */
+    create(params: CompanyCreateParams): Promise<CompanyCreateResult>;
+    /** List companies with optional filters. */
+    list(params?: CompanyListParams): Promise<{
+        data: Company[];
+        total: number;
+    }>;
+    /** Get a single company by ID. */
+    get(companyId: number): Promise<Company>;
+    /** Get contacts belonging to a company. */
+    contacts(companyId: number, limit?: number, offset?: number): Promise<{
+        data: CompanyContact[];
+        total: number;
+    }>;
+    /** Update a company (partial). */
+    update(companyId: number, fields: CompanyUpdateParams): Promise<{
+        updated: number;
+    }>;
+    /** Delete a company (soft-delete). */
+    delete(companyId: number): Promise<{
+        deleted: boolean;
+    }>;
+    /** List custom company columns. Pass listId to include list-specific columns. */
+    listColumns(listId?: number): Promise<{
+        data: CompanyColumn[];
+    }>;
+    /** Create a custom company column. Global if list_id is omitted, list-scoped otherwise. */
+    createColumn(params: CompanyColumnCreateParams): Promise<CompanyColumn>;
+};