@graph8/sdk 0.13.0 → 0.14.0

package/dist/react.d.mts

@@ -1767,6 +1767,10 @@ interface CustomObjectAttribute {
     /** 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>;
 }
@@ -1782,6 +1786,8 @@ interface CustomObjectRecord {
      */
     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;
 }
@@ -1826,10 +1832,7 @@ interface ObjectPagination {
  * 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".
+ * 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
@@ -1842,10 +1845,16 @@ interface ObjectPagination {
  *      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.
+ *      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}
@@ -1889,12 +1898,16 @@ declare const createObjectsClient: (apiKey: string, apiUrl?: string) => {
      * 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>;
+    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.
@@ -1902,6 +1915,272 @@ declare const createObjectsClient: (apiKey: string, apiUrl?: string) => {
     history(objectSlug: string, recordId: string, limit?: number): Promise<CustomObjectHistory>;
 };
 
+/**
+ * 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. */
+type DeploymentStatus = "queued" | "building" | "promoting" | "deployed" | "failed" | "rolled_back";
+type DomainVerificationStatus = "pending" | "verified" | "failed" | "revoked";
+type SourceProvider = "github" | "gitlab" | "bitbucket";
+type SchemaVersionStatus = "draft" | "published" | "deprecated";
+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;
+}
+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;
+}
+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;
+}
+interface DomainVerificationInstructions {
+    domain: AppDomain;
+    record_type: "TXT";
+    record_name: string;
+    record_value: string;
+}
+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;
+}
+interface AppSourceParams {
+    repo_url: string;
+    provider: SourceProvider;
+    default_branch?: string;
+    credential_ref?: string;
+}
+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;
+}
+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;
+}
+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[];
+}
+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[];
+    }>;
+};
+
 /**
  * App lifecycle. `draft` serves no traffic; `published` is live; `suspended` is a
  * platform action and cannot be set through this client; `archived` is retired.
@@ -3486,6 +3765,7 @@ declare const useG8: () => {
         _tasks: ReturnType<typeof createTasksClient> | null;
         _fields: ReturnType<typeof createFieldsClient> | null;
         _apps: ReturnType<typeof createAppsClient> | null;
+        _appPlatform: ReturnType<typeof createAppPlatformClient> | null;
         _objects: ReturnType<typeof createObjectsClient> | null;
         _deals: ReturnType<typeof createDealsClient> | null;
         _inbox: ReturnType<typeof createInboxClient> | null;
@@ -3759,6 +4039,43 @@ declare const useG8: () => {
             usage(appId: string, period?: string): Promise<AppUsageSummary>;
             getLimit(appId: string): Promise<AppLimit | null>;
         };
+        get appPlatform(): {
+            setSource(appId: string, params: AppSourceParams): Promise<Record<string, unknown>>;
+            clearSource(appId: string): Promise<Record<string, unknown>>;
+            listDeployments(appId: string): Promise<{
+                data: Deployment[];
+            }>;
+            deploy(appId: string, params: CreateDeploymentParams): Promise<Deployment>;
+            getDeployment(appId: string, deploymentId: string): Promise<Deployment>;
+            activeDeployment(appId: string): Promise<Deployment | null>;
+            promote(appId: string, deploymentId: string, imageDigest: string): Promise<Deployment>;
+            rollback(appId: string, deploymentId: string): Promise<Deployment>;
+            deploymentLogs(appId: string, deploymentId: string, tailLines?: number): Promise<AppLogs>;
+            logs(appId: string, tailLines?: number): Promise<AppLogs>;
+            listDomains(appId: string): Promise<{
+                data: AppDomain[];
+            }>;
+            claimDomain(appId: string, hostname: string): Promise<DomainVerificationInstructions>;
+            verifyDomain(appId: string, hostname: string): Promise<AppDomain>;
+            releaseDomain(appId: string, hostname: string): Promise<{
+                hostname: string;
+                released: boolean;
+            }>;
+            listSecrets(appId: string): Promise<{
+                data: AppSecretMetadata[];
+            }>;
+            putSecret(appId: string, secretKey: string, providerRef?: string): Promise<AppSecretMetadata>;
+            deleteSecret(appId: string, secretKey: string): Promise<{
+                secret_key: string;
+                removed: boolean;
+            }>;
+            publishSchemaVersion(appId: string, objects: unknown[]): Promise<{
+                version: SchemaVersion;
+            }>;
+            listSchemaVersions(appId: string): Promise<{
+                data: SchemaVersion[];
+            }>;
+        };
         get objects(): {
             list(): Promise<{
                 data: CustomObject[];
@@ -3773,8 +4090,11 @@ declare const useG8: () => {
             }>;
             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>;
+            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(): {