@graph8/sdk 0.251.0 → 0.262.0

package/dist/types/README.md

@@ -0,0 +1,7 @@
+# dist/types: readable declarations
+
+One file per hand-written client (`contacts.d.ts`, `deals.d.ts`, `sequences.d.ts`, ...). For reading:
+the compiler uses the bundled `dist/index.d.ts`, so import types from `@graph8/sdk` in code.
+
+The generated `g8.api` types are not here. Each namespace has a self-contained slice in
+`docs/api/<namespace>.d.ts` (for example `docs/api/contacts.d.ts`). Start at `docs/agents.md`.

package/dist/types/agency.d.ts

@@ -0,0 +1,20 @@
+export interface AgencyInfo {
+    agency_org_id: string;
+    agency_org_name: string | null;
+    is_agency: boolean;
+    client_count: number;
+    /** Request header to set when operating a client org (e.g. "X-Target-Org-Id"). */
+    target_header: string;
+}
+export interface AgencyClient {
+    /** Pass this as the `X-Target-Org-Id` header to operate this client org. */
+    org_id: string;
+}
+export declare const createAgencyClient: (apiKey: string, apiUrl?: string) => {
+    /** Describe the agency credential: agency org + authorized client count. */
+    me(): Promise<AgencyInfo>;
+    /** List the client orgs this agency key may target via `X-Target-Org-Id`. */
+    clients(): Promise<{
+        data: AgencyClient[];
+    }>;
+};

package/dist/types/agentSetup.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `npx @graph8/sdk init-agent`: tell the coding agents in a project how to use
+ * this SDK.
+ *
+ * WHY
+ * ---
+ * The package ships a full agent guide (`docs/agents.md`), but an agent only
+ * reads it if something points it there. Each agent looks for instructions in
+ * its own place, in the USER'S project:
+ *
+ *   Claude Code  .claude/skills/graph8-sdk/SKILL.md   (a skill: loaded only when
+ *                                                      the task involves graph8)
+ *   Codex (and Cursor, Copilot, Jules, Amp, ...)  AGENTS.md
+ *   Cursor       .cursor/rules/graph8-sdk.mdc
+ *
+ * This writes a short, version-independent pointer into each: the rules that
+ * prevent the common mistakes, and where in node_modules the full guide and
+ * per-area reference live. It never touches the user's own text: the AGENTS.md
+ * section sits between markers and is replaced in place on re-runs, and the
+ * other two files are owned by this tool.
+ *
+ * Pure functions here; the CLI in ./cli.ts does the file I/O.
+ */
+export type AgentTarget = "claude" | "codex" | "cursor";
+export declare const ALL_TARGETS: readonly AgentTarget[];
+export declare const MARKER_START = "<!-- graph8-sdk:start (managed by `npx @graph8/sdk init-agent`; edits inside are overwritten) -->";
+export declare const MARKER_END = "<!-- graph8-sdk:end -->";
+/** The rules every agent gets, whatever file they land in. */
+export declare function coreInstructions(): string;
+export declare function claudeSkill(): string;
+export declare function cursorRule(): string;
+export declare function agentsMdSection(): string;
+/**
+ * Insert or replace the managed section in an existing AGENTS.md, leaving
+ * everything outside the markers byte-for-byte unchanged.
+ */
+export declare function upsertAgentsMd(existing: string | null): string;
+export interface PlannedWrite {
+    target: AgentTarget;
+    path: string;
+    /** Content after the write. */
+    content: string;
+    /** "create" | "update" | "unchanged" */
+    action: "create" | "update" | "unchanged";
+}
+/**
+ * Work out every file change for the chosen agents. `read` returns a file's
+ * current content (or null when it does not exist); paths are relative to the
+ * project root.
+ */
+export declare function planAgentSetup(targets: readonly AgentTarget[], read: (path: string) => string | null): PlannedWrite[];
+export interface InitAgentOptions {
+    targets: AgentTarget[];
+    dryRun: boolean;
+}
+export declare const INIT_AGENT_USAGE = "Usage: npx @graph8/sdk init-agent [--claude] [--codex] [--cursor] [--dry-run]\n\nPoint the coding agents in this project at the @graph8/sdk agent guide.\nWith no agent flag, sets up all three:\n  --claude   .claude/skills/graph8-sdk/SKILL.md   (Claude Code skill)\n  --codex    AGENTS.md, managed section            (Codex, Cursor, Copilot, ...)\n  --cursor   .cursor/rules/graph8-sdk.mdc         (Cursor rule)\n  --dry-run  print what would change, write nothing\nRe-running updates the files in place; your own AGENTS.md text is never touched.";
+export declare function parseInitAgentArgs(argv: string[]): InitAgentOptions;

package/dist/types/api.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The generated-contract client: every published Developer API operation,
+ * typed, reachable from one object.
+ *
+ * WHAT THIS IS FOR
+ * ----------------
+ * The hand-written clients in this package (`g8.contacts`, `g8.deals`, ...) are
+ * the ergonomic layer. They are deliberately opinionated — they unwrap
+ * envelopes, rename fields, and only exist for surfaces someone sat down and
+ * wrote. That is exactly why they covered 260 of 587 operations: writing one
+ * per surface does not keep pace with the API.
+ *
+ * `g8.api` is the other half. It is generated from
+ * `developer-contract/openapi.json`, so it covers 100% of the contract by
+ * construction and a CI drift check keeps it there. It returns the response
+ * envelope EXACTLY as the contract declares it and renames nothing.
+ *
+ * NOTHING HERE REPLACES ANYTHING. Every existing export keeps its shape; this
+ * is a new namespace alongside them.
+ *
+ *   const contacts = await g8.api.contacts.listContacts({ query: { limit: 50 } });
+ *   const meeting  = await g8.api.call("get_meeting_meetings__meeting_id__get", {
+ *     path: { meeting_id: "..." },
+ *   });
+ *
+ * WHY A DISPATCHER RATHER THAN 587 GENERATED METHODS
+ * --------------------------------------------------
+ * Generated methods would be ~6k lines of runtime JavaScript that no bundler
+ * can drop from a singleton client. Here the runtime is one data table
+ * (`API_OPERATIONS`) plus the ~100 lines below; the 587 typed signatures live
+ * in `.d.ts` and are erased before anything reaches a browser. Namespaces are
+ * materialised lazily, so touching `g8.api.contacts` allocates closures for
+ * Contacts only.
+ *
+ * It reuses `request()` from `./http` — the same transport, retries,
+ * idempotency-key minting and typed `G8Error` every other client already uses.
+ * There is exactly one transport in this package and this does not add a
+ * second.
+ */
+import { type RequestOptions } from "./http";
+import { type ApiHttpMethod, type ApiOperationId, type ApiTag } from "./generated/operations";
+import type { ApiOperationMap } from "./generated/operation-types";
+import type { ApiNamespaceMap } from "./generated/namespaces";
+/**
+ * Prefix every contract path is relative to.
+ *
+ * The contract's `servers` block is `https://be.graph8.com/api/v1`, so its paths
+ * omit the prefix while the SDK's own call sites include it. Recording it once
+ * here keeps the route table small and the two conventions reconciled in one
+ * place.
+ */
+export declare const API_BASE_PATH = "/api/v1";
+/** A route-table row, expanded into something readable. */
+export interface ApiOperationInfo {
+    /** Frozen public operationId. */
+    id: ApiOperationId;
+    method: ApiHttpMethod;
+    /** Full path including `/api/v1`. */
+    path: string;
+    /** Namespace this operation is reachable under (`g8.api[tag][member]`). */
+    tag: ApiTag;
+    /** Member name inside that namespace. */
+    member: string;
+    /** `x-graph8-tier` — read / write / destructive / billable / external. */
+    tier: string | null;
+    /** `x-graph8-scope` — the API-key scope that gates this operation. */
+    scope: string | null;
+}
+/** Typed input accepted by an operation: `{ path?, query?, headers?, body? }`. */
+export type ApiInput<Id extends ApiOperationId> = ApiOperationMap[Id]["input"];
+/** Typed response envelope an operation resolves to. */
+export type ApiOutput<Id extends ApiOperationId> = ApiOperationMap[Id]["output"];
+/**
+ * Item type yielded by `paginate()` — the element type of the envelope's `data`
+ * array when there is one, `unknown` otherwise.
+ */
+export type ApiPageItem<Id extends ApiOperationId> = ApiOutput<Id> extends {
+    data?: infer D;
+} ? D extends readonly (infer Item)[] ? Item : unknown : unknown;
+/**
+ * Per-call transport overrides. `method`, `body` and `query` are owned by the
+ * dispatcher (they come from the contract and the typed input), so they are not
+ * overridable — everything else `request()` accepts is.
+ */
+export type ApiCallOptions = Omit<RequestOptions, "method" | "body" | "query">;
+/**
+ * `input` becomes optional exactly when every member of it is optional.
+ *
+ * `{} extends T` is true only when T has no required property, so an operation
+ * with a required body still forces the caller to pass one, and a pure GET with
+ * optional filters can be called with no arguments at all.
+ */
+type ApiArgs<Id extends ApiOperationId> = {} extends ApiInput<Id> ? [input?: ApiInput<Id>, options?: ApiCallOptions] : [input: ApiInput<Id>, options?: ApiCallOptions];
+/** One generated namespace member, e.g. `client.contacts.listContacts`. */
+export type ApiMethod<Id extends ApiOperationId> = (...args: ApiArgs<Id>) => Promise<ApiOutput<Id>>;
+/**
+ * The tag namespaces, derived from the generated name map. Adding an operation
+ * to the contract adds a member here with no hand-written code.
+ */
+export type ApiNamespaces = {
+    [Tag in keyof ApiNamespaceMap]: {
+        [Member in keyof ApiNamespaceMap[Tag]]: ApiMethod<ApiNamespaceMap[Tag][Member] & ApiOperationId>;
+    };
+};
+/** The dispatcher half of the client, without the generated namespaces. */
+export interface ApiDispatcher {
+    /** Call any published operation by its frozen operationId. */
+    call<Id extends ApiOperationId>(operationId: Id, ...args: ApiArgs<Id>): Promise<ApiOutput<Id>>;
+    /**
+     * Iterate every item of a cursor-paginated list operation, following
+     * `pagination.next_cursor` until it runs out.
+     */
+    paginate<Id extends ApiOperationId>(operationId: Id, ...args: ApiArgs<Id>): AsyncGenerator<ApiPageItem<Id>, void, unknown>;
+    /** Metadata for one operation — method, full path, tier and required scope. */
+    operation(operationId: ApiOperationId): ApiOperationInfo;
+    /** Metadata for every published operation, sorted by operationId. */
+    operations(): ApiOperationInfo[];
+}
+export type ApiClient = ApiDispatcher & ApiNamespaces;
+/**
+ * Build a client covering every operation the Developer API publishes.
+ *
+ * Additive: `g8.api` is wired to this in `core.ts`, and no existing client,
+ * export or signature changes.
+ */
+export declare function createApiClient(apiKey: string, apiUrl?: string): ApiClient;
+export {};

package/dist/types/appClient.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Hosted app-platform clients (M6-9).
+ *
+ * Two entry points, both additive to `@graph8/sdk` and independent of the
+ * `g8` tracking/API-key singleton:
+ *
+ *   - `createGraph8AppClient` — BROWSER client. Exchanges the caller's
+ *     PropelAuth token for a short-lived app token, refreshes it on/near expiry,
+ *     and attaches `Authorization: Bearer <app-token>` to every call. It NEVER
+ *     accepts a permanent org API key for browser init (the whole reason the
+ *     token-exchange exists).
+ *   - `createGraph8ServiceClient` — BACKEND client. Exchanges service
+ *     client-credentials for a service app token and sends `X-Target-Org-Id`
+ *     for the single configured tenant on every call.
+ *
+ * Both expose a token-bound `request()` — the hardened `request()` core with the
+ * minted app token attached — so callers reach Developer API routes with the
+ * app token and reuse the core's typed `G8Error`, retries, idempotency, and
+ * cursor pagination. The typed `apps` (control-plane) and `objects`
+ * (custom-object CRUD) resource modules are DEFERRED until their backend routes
+ * ship and freeze (M6-3 / M6-5); only the auth clients ship here.
+ */
+import { type AppRequest } from "./appTokens";
+export type { AppTokenResponse, TokenManager, AppRequest, AppRequestOptions } from "./appTokens";
+/** Config for {@link createGraph8AppClient} (browser). No API key is accepted. */
+export interface Graph8AppClientConfig {
+    /** Target app id (dapp_-prefixed). */
+    appId: string;
+    /** The client org this browser session acts in (informational; the server
+     *  derives the authoritative tenant from the validated PropelAuth principal). */
+    tenantOrgId: string;
+    /** Returns the caller's current PropelAuth token (sync or async). */
+    getPropelAuthToken: () => string | Promise<string>;
+    /** Scopes to embed in the minted app token. */
+    scopes?: string[];
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A browser app-platform client. */
+export interface Graph8AppClient {
+    readonly appId: string;
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the app token and attaches
+     *  `Authorization: Bearer <app-token>` to every Developer API call. */
+    readonly request: AppRequest;
+    /** Return the current app token, refreshing on/near expiry (`force` refreshes now). */
+    getAppToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BROWSER app-platform client backed by PropelAuth->app-token exchange.
+ * Refuses an org API key / write key — those must never reach a browser.
+ */
+export declare function createGraph8AppClient(config: Graph8AppClientConfig): Graph8AppClient;
+/** Config for {@link createGraph8ServiceClient} (backend / server-to-server). */
+export interface Graph8ServiceClientConfig {
+    /** Service credential client id. */
+    clientId: string;
+    /** Service credential client secret (checked against the stored hash). */
+    clientSecret: string;
+    /** The single consented client org this backend acts for (sent as X-Target-Org-Id). */
+    tenantOrgId: string;
+    /** Scopes to embed in the minted service token. */
+    scopes?: string[];
+    /** Requested token TTL; the server clamps it into its service band. */
+    ttlSeconds?: number;
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A backend service app-platform client. */
+export interface Graph8ServiceClient {
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the service token, attaches it, and
+     *  sends `X-Target-Org-Id` for the one consented tenant on every call. */
+    readonly request: AppRequest;
+    /** Return the current service token, refreshing on/near expiry (`force` refreshes now). */
+    getServiceToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BACKEND service client backed by client-credentials->service-token
+ * exchange. Every request carries `X-Target-Org-Id: <tenantOrgId>` for the one
+ * configured consented tenant.
+ */
+export declare function createGraph8ServiceClient(config: Graph8ServiceClientConfig): Graph8ServiceClient;

package/dist/types/appPlatform.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Hosted app platform — deployments, domains, secrets, source and logs (M9 J14).
+ *
+ * WHAT WAS MISSING. `apps.ts` covered creating an app and reading its installs,
+ * usage and limit. Everything that actually SHIPS one -- binding a source,
+ * queueing a deployment, promoting it, attaching a hostname, reading why a build
+ * failed -- had no client at all. That is why the build portal is read-only: not
+ * because the routes are absent, but because nothing typed reached them.
+ *
+ * EVERY RESPONSE ON THIS SURFACE IS WRAPPED as `{data, pagination}`, and
+ * `pagination` is always null here -- none of these routes paginate. The helpers
+ * below unwrap `data` so callers work with the record, except where the list IS
+ * the answer.
+ *
+ * DELIBERATELY ABSENT, and each for a reason:
+ *
+ *   * `POST /apps/{id}/deployments/{id}/status` -- authenticated with the build
+ *     CONTROLLER credential, not a builder's API key. An SDK method for it would
+ *     imply a customer can move their own deployment through the state machine.
+ *   * `GET /app-platform/tls-authorize` -- Caddy's on-demand-TLS ask hook. Public,
+ *     unauthenticated, returns a bare 200 or 404 with no body. It is edge
+ *     plumbing, not a customer API.
+ */
+/** The six frozen values. Not widened to `string`: a client that switches on the
+ *  status should get a compile error when a new state is added. */
+export type DeploymentStatus = "queued" | "building" | "promoting" | "deployed" | "failed" | "rolled_back";
+export type DomainVerificationStatus = "pending" | "verified" | "failed" | "revoked";
+export type SourceProvider = "github" | "gitlab" | "bitbucket";
+export type SchemaVersionStatus = "draft" | "published" | "deprecated";
+export interface Deployment {
+    deployment_id: string;
+    app_id: string;
+    /** One of `DeploymentStatus`. Typed as the union, but the server sends a plain
+     *  string -- treat an unrecognised value as forward compatibility, not an error. */
+    status: DeploymentStatus;
+    source_ref: string | null;
+    image_digest: string | null;
+    schema_version_id: string | null;
+    /** Sanitized at the WRITE. One line. The detail is in `logs()`. */
+    last_error_sanitized: string | null;
+    created_at: string | null;
+    deployed_at: string | null;
+    build_started_at: string | null;
+    build_finished_at: string | null;
+    /** Measured `building` -> `promoting`, NOT to `deployed`: `deployed` is reached
+     *  after traffic is taken, so measuring to it would count the promotion too. */
+    build_seconds: number | null;
+}
+export interface CreateDeploymentParams {
+    /** A COMMIT-ish, never a branch name. A branch moves, so a deployment recorded
+     *  against one cannot answer "what is running right now" a week later. The
+     *  server enforces length only -- this convention is the caller's to keep. */
+    source_ref: string;
+    /** Pins the custom-object schema this build expects, so a rollback restores the
+     *  matching schema and not merely the matching image. */
+    schema_version_id?: string;
+}
+export interface AppDomain {
+    domain_id: string;
+    app_id: string;
+    /** The canonical normalized form -- lowercased, trailing dot stripped, IDNA
+     *  encoded. NOT what you submitted. */
+    hostname: string;
+    status: DomainVerificationStatus;
+    verification_token: string | null;
+    created_at: string | null;
+    verified_at: string | null;
+}
+export interface DomainVerificationInstructions {
+    domain: AppDomain;
+    record_type: "TXT";
+    record_name: string;
+    record_value: string;
+}
+export interface AppSecretMetadata {
+    secret_key: string;
+    /** A POINTER into your secret manager, never the secret. graph8 has no column
+     *  for a value and cannot grow one. */
+    provider_ref: string | null;
+    created_at: string | null;
+    rotated_at: string | null;
+}
+export interface AppSourceParams {
+    repo_url: string;
+    provider: SourceProvider;
+    default_branch?: string;
+    credential_ref?: string;
+}
+export interface SchemaVersion {
+    schema_version_id: string;
+    app_id: string;
+    version: number;
+    digest: string;
+    status: SchemaVersionStatus;
+    manifest: Record<string, unknown>;
+    created_at: string | null;
+    published_at: string | null;
+    deprecated_at: string | null;
+}
+export interface ContainerLog {
+    pod: string;
+    container: string;
+    /** `init` steps run to completion before the pod's containers start. A build is
+     *  four init steps (fetch, scan-source, build, scan-image) then one container
+     *  (push), so this is how you tell which step you are looking at. */
+    kind: "init" | "container";
+    text: string;
+    /** The tail hit the per-container byte cap. Earlier output exists and was not
+     *  returned. */
+    truncated: boolean;
+}
+export interface AppLogs {
+    app_id: string;
+    /** Set for build logs; null for the running app's logs. */
+    deployment_id: string | null;
+    namespace: string;
+    tail_lines: number;
+    /**
+     * Always true, and it means only that graph8's credential patterns ran.
+     * It is NOT a claim the output is safe to publish: these are your own build and
+     * application logs, and an application can print a secret in a shape no pattern
+     * matches.
+     */
+    redacted: boolean;
+    containers: ContainerLog[];
+}
+/** Lines per container. The server refuses anything outside 1-2000 with a 422
+ *  rather than clamping, so the bound is worth knowing before you send it. */
+export declare const MIN_TAIL_LINES = 1;
+export declare const MAX_TAIL_LINES = 2000;
+export declare const createAppPlatformClient: (apiKey: string, apiUrl?: string) => {
+    /**
+     * Bind the repository an app builds from.
+     *
+     * `repo_url` must be fetchable -- `https://`, `ssh://` or `git@`, with no
+     * whitespace. A `file://` or bare path is refused with 422, because a build
+     * that can read the builder's filesystem is a build that can read ours.
+     *
+     * `credential_ref` is a POINTER into your secret manager, not a token.
+     */
+    setSource(appId: string, params: AppSourceParams): Promise<Record<string, unknown>>;
+    /** Unbind the source. Returns the full app with every source field null. */
+    clearSource(appId: string): Promise<Record<string, unknown>>;
+    /** Every deployment for this app, newest first. Never 404s for an app with none. */
+    listDeployments(appId: string): Promise<{
+        data: Deployment[];
+    }>;
+    /**
+     * Queue a deployment. Returns `201` with `status: "queued"` -- nothing builds
+     * as a side effect of this call; the build controller picks it up.
+     *
+     * NOT idempotent: two identical calls create two deployments.
+     */
+    deploy(appId: string, params: CreateDeploymentParams): Promise<Deployment>;
+    /** Fetch one deployment. The polling endpoint for a build loop. */
+    getDeployment(appId: string, deploymentId: string): Promise<Deployment>;
+    /**
+     * The deployment currently serving traffic, or `null`.
+     *
+     * `null` is a real answer with a 200, not a 404: "this app has never shipped"
+     * is information, while a 404 would read as "no such app".
+     */
+    activeDeployment(appId: string): Promise<Deployment | null>;
+    /**
+     * Promote a built deployment to serve traffic. Anything it displaces moves to
+     * `rolled_back` in the same transaction, so there is never a moment with two
+     * live deployments.
+     *
+     * `409` when the state machine forbids it -- a deployment cannot become
+     * `deployed` without having been built, and a `failed` one cannot be revived.
+     * A retry is a new deployment, not a resurrection.
+     */
+    promote(appId: string, deploymentId: string, imageDigest: string): Promise<Deployment>;
+    /** Roll back a deployment that is currently serving. Only a `deployed` one may be. */
+    rollback(appId: string, deploymentId: string): Promise<Deployment>;
+    /**
+     * Why a build failed. Returns every step of the build pod in the order
+     * Kubernetes runs them; a step that has not started yet is omitted rather
+     * than returned empty.
+     *
+     * An empty `containers` list is not an error -- build pods are reaped an hour
+     * after they finish, so logs for an older deployment are genuinely gone.
+     * `last_error_sanitized` on the deployment is what survives.
+     *
+     * `503` means graph8 could not reach the cluster, which is deliberately
+     * different from an empty `200`: one means we could not look, the other means
+     * your build produced no output.
+     */
+    deploymentLogs(appId: string, deploymentId: string, tailLines?: number): Promise<AppLogs>;
+    /**
+     * What the running app is printing. The app's own pods only -- the per-app
+     * egress proxy shares the namespace and is deliberately excluded.
+     *
+     * Empty until a deployment reaches `deployed`.
+     */
+    logs(appId: string, tailLines?: number): Promise<AppLogs>;
+    /** Every hostname claimed for this app, whatever its verification state. */
+    listDomains(appId: string): Promise<{
+        data: AppDomain[];
+    }>;
+    /**
+     * Claim a hostname and get the TXT record that proves you own it.
+     *
+     * Returns `201`, and the domain is NESTED at `data.domain` -- this is the one
+     * route on the surface whose payload is not the record itself. Hostnames are
+     * globally unique, so a host another app holds is refused.
+     */
+    claimDomain(appId: string, hostname: string): Promise<DomainVerificationInstructions>;
+    /**
+     * Check DNS for the TXT record and advance the domain to `verified`.
+     *
+     * Idempotent: verifying an already-verified domain re-checks and stays
+     * verified, so it is safe to re-run after a DNS change. Send no body -- the
+     * record in DNS is the payload.
+     */
+    verifyDomain(appId: string, hostname: string): Promise<AppDomain>;
+    /**
+     * Release a claimed hostname.
+     *
+     * A HARD delete. Hostnames are globally unique, so a row left behind in any
+     * status keeps the host burned for every other builder. Releasing one you
+     * already released is a `404`, because after the first call the claim
+     * genuinely does not exist.
+     *
+     * Returns the NORMALIZED hostname, which may differ from what you passed.
+     */
+    releaseDomain(appId: string, hostname: string): Promise<{
+        hostname: string;
+        released: boolean;
+    }>;
+    /**
+     * Which secrets this app declares, and when each was last rotated.
+     *
+     * NEVER returns a value. graph8 stores a POINTER into your secret manager and
+     * has no column for the secret itself.
+     */
+    listSecrets(appId: string): Promise<{
+        data: AppSecretMetadata[];
+    }>;
+    /**
+     * Declare a secret, or rotate the pointer to it.
+     *
+     * `providerRef` is a REFERENCE, and the server rejects anything that looks
+     * like a credential -- a value starting `bearer `, `sk-`, `ghp_`, `xox` and
+     * friends is a 422. That refusal is the feature: it catches the mistake of
+     * pasting the secret where its address belongs.
+     */
+    putSecret(appId: string, secretKey: string, providerRef?: string): Promise<AppSecretMetadata>;
+    /** Undeclare a secret. A key the app never declared is a 404, so a typo is
+     *  never reported as a successful removal. */
+    deleteSecret(appId: string, secretKey: string): Promise<{
+        secret_key: string;
+        removed: boolean;
+    }>;
+    /**
+     * Publish a custom-object schema version. Returns `201`.
+     *
+     * Takes only the `objects` list, not a whole `graph8.app.yaml`: the rest of
+     * that file is app metadata the control plane already holds, and accepting it
+     * here would create a second place for it to disagree.
+     */
+    publishSchemaVersion(appId: string, objects: unknown[]): Promise<{
+        version: SchemaVersion;
+    }>;
+    /** Every schema version this app has published. Empty array, never 404. */
+    listSchemaVersions(appId: string): Promise<{
+        data: SchemaVersion[];
+    }>;
+};