@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/appDomains.md

@@ -0,0 +1,281 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.appDomains`: App Domains
+
+5 operations (2 read, 2 write, 1 destructive).
+
+4 of these also have a hand-written method (`g8.appPlatform`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [appDomains.d.ts](appDomains.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`claimAppDomain`](#op-claimappdomain) ★ | `POST /api/v1/apps/{app_id}/domains` | write | `apps:write` | Claim App Domain |
+| [`listAppDomains`](#op-listappdomains) ★ | `GET /api/v1/apps/{app_id}/domains` | read | `apps:read` | List App Domains |
+| [`releaseAppDomain`](#op-releaseappdomain) ★ | `DELETE /api/v1/apps/{app_id}/domains/{hostname}` | destructive | `apps:delete` | Release App Domain |
+| [`tlsAuthorize`](#op-tlsauthorize) | `GET /api/v1/app-platform/tls-authorize` | read |  | Tls Authorize |
+| [`verifyAppDomain`](#op-verifyappdomain) ★ | `POST /api/v1/apps/{app_id}/domains/{hostname}/verify` | write | `apps:write` | Verify App Domain |
+
+---
+
+<a id="op-claimappdomain"></a>
+
+### `g8.api.appDomains.claimAppDomain(input)`
+
+**Claim App Domain**
+
+- HTTP: `POST /api/v1/apps/{app_id}/domains`
+- operationId: `claim_app_domain_apps__app_id__domains_post` (also callable as `g8.api.call("claim_app_domain_apps__app_id__domains_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.claimDomain()`](../sdk-clients.md#g8-appplatform-claimdomain)
+
+Claim a hostname and return the TXT record proving you control it.
+
+409 when another app already holds the host. Hostnames are globally unique,
+and a silent overwrite would let one builder take another's traffic -- which
+is why `claim_domain` raises rather than upserting.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `ClaimDomainRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`ClaimDomainRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.hostname` | `string` | yes | The hostname to serve this app on. Normalized server-side: case, a trailing dot and unicode all resolve to one canonical form. max length 253 |
+
+**Returns** `ApiResponse_DomainVerificationInstructions_`: the envelope `{ data: DomainVerificationInstructions, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DomainVerificationInstructions` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `DomainResponse` | yes |  |
+| `record_name` | `string` | yes | Create the record at this name, e.g. _graph8-challenge.app.example.com |
+| `record_value` | `string` | yes |  |
+| `record_type` | `string` | no | default `"TXT"` |
+
+**Example**
+
+```ts
+const result = await g8.api.appDomains.claimAppDomain({ path: { app_id: "id" }, body: { hostname: "Example" } });
+```
+
+---
+
+<a id="op-listappdomains"></a>
+
+### `g8.api.appDomains.listAppDomains(input)`
+
+**List App Domains**
+
+- HTTP: `GET /api/v1/apps/{app_id}/domains`
+- operationId: `list_app_domains_apps__app_id__domains_get` (also callable as `g8.api.call("list_app_domains_apps__app_id__domains_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.listDomains()`](../sdk-clients.md#g8-appplatform-listdomains)
+
+Every hostname claimed for this app, whatever its verification state.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_DomainResponse__`: the envelope `{ data: Array<DomainResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DomainResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `domain_id` | `string` | yes |  |
+| `hostname` | `string` | yes | The canonical, normalized form -- not necessarily what was submitted. |
+| `status` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `verified_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDomains.listAppDomains({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-releaseappdomain"></a>
+
+### `g8.api.appDomains.releaseAppDomain(input)`
+
+**Release App Domain**
+
+- HTTP: `DELETE /api/v1/apps/{app_id}/domains/{hostname}`
+- operationId: `release_app_domain_apps__app_id__domains__hostname__delete` (also callable as `g8.api.call("release_app_domain_apps__app_id__domains__hostname__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+- ★ Hand-written: [`g8.appPlatform.releaseDomain()`](../sdk-clients.md#g8-appplatform-releasedomain)
+
+Release a claimed hostname.
+
+Hostnames are globally unique across every app
+(``uq_developer_app_domains_hostname``), so one typo permanently burned that
+host for every builder on the platform with no public way to undo it. The
+repository had get, list, claim and set_status, and no delete at all.
+
+A HARD delete, not a `revoked` status. The uniqueness index does not care
+about status, so a row left behind in any state keeps the host claimed while
+looking to the builder like it was released.
+
+OWNERSHIP IS CHECKED AGAINST THE STORED CLAIM, not just the app in the path.
+`_require_own_app` proves the caller owns THIS app; the second check proves
+the hostname belongs to that same app. Without it a builder could pass their
+own app id and any hostname, and delete a competitor's claim -- the one thing
+global uniqueness makes irreversible.
+
+404 for an unknown host or one held by another app, never 403: a 403 would
+make a competitor's claim discoverable by probing.
+
+Idempotent within your own app: releasing a host you have already released is
+a 404, because after the first call the claim genuinely does not exist. The
+delete itself reports whether a row went, and both answers are correct.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.hostname` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.appDomains.releaseAppDomain({ path: { app_id: "id", hostname: "Example" } });
+```
+
+---
+
+<a id="op-tlsauthorize"></a>
+
+### `g8.api.appDomains.tlsAuthorize(input)`
+
+**Tls Authorize**
+
+- HTTP: `GET /api/v1/app-platform/tls-authorize`
+- operationId: `tls_authorize_app_platform_tls_authorize_get` (also callable as `g8.api.call("tls_authorize_app_platform_tls_authorize_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: none published
+
+Caddy on-demand-TLS ask endpoint. PUBLIC, UNAUTHENTICATED, FAILS CLOSED.
+
+Caddy issues a certificate when this returns 2xx. Answering 2xx for a host we
+do not own would let anyone who points DNS at our edge have a publicly
+trusted certificate minted by us.
+
+2xx ONLY for a hostname that exists AND is `verified`. Everything else is a
+bare 404 with no body: distinguishing "unknown" from "known but unverified"
+would make this a free oracle for which customers are onboarding.
+
+It IS published in the contract. `include_in_schema=False` was the first
+instinct -- it is infrastructure plumbing, not a customer API -- and it broke
+an invariant: the operation manifest is derived from the OpenAPI spec while
+`operation_tiers` is derived from the route table, so hiding a route makes
+the two span different universes.
+`test_the_manifest_covers_the_WHOLE_operation_universe` exists to catch
+exactly that, and it went red on qa.
+
+Hiding it was never a security control anyway -- the endpoint fails closed on
+its own, and its existence is inferable from any Caddy config. Consistency
+between the published contract and the route table is worth more than the
+tidiness of an unlisted endpoint.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.appDomains.tlsAuthorize({ query: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-verifyappdomain"></a>
+
+### `g8.api.appDomains.verifyAppDomain(input)`
+
+**Verify App Domain**
+
+- HTTP: `POST /api/v1/apps/{app_id}/domains/{hostname}/verify`
+- operationId: `verify_app_domain_apps__app_id__domains__hostname__verify_post` (also callable as `g8.api.call("verify_app_domain_apps__app_id__domains__hostname__verify_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.verifyDomain()`](../sdk-clients.md#g8-appplatform-verifydomain)
+
+Check DNS for the TXT record and advance the domain to `verified`.
+
+Idempotent: verifying an already-verified domain re-checks and stays verified,
+so a builder can re-run it after a DNS change without a special path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.hostname` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_DomainResponse_`: the envelope `{ data: DomainResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DomainResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `domain_id` | `string` | yes |  |
+| `hostname` | `string` | yes | The canonical, normalized form -- not necessarily what was submitted. |
+| `status` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `verified_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.appDomains.verifyAppDomain({ path: { app_id: "id", hostname: "Example" } });
+```

package/docs/api/appLogs.d.ts

@@ -0,0 +1,120 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.appLogs` (App Logs): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"get_app_logs_apps__app_id__logs_get">;
+ *
+ * Reference with examples: appLogs.md
+ */
+/* eslint-disable */
+
+/** `g8.api.appLogs.<member>` -> the operationId it calls. */
+export interface AppLogsMembers {
+  getAppLogs: "get_app_logs_apps__app_id__logs_get";
+  getDeploymentLogs: "get_deployment_logs_apps__app_id__deployments__deployment_id__logs_get";
+}
+
+/** Input and output of every `g8.api.appLogs` operation, keyed by operationId. */
+export interface AppLogsOperations {
+  /**
+   * GET /apps/{app_id}/logs
+   * Get App Logs
+   * tier: read · scope: apps:read
+   */
+  get_app_logs_apps__app_id__logs_get: {
+    input: {
+    path: {
+      app_id: string;
+    };
+    query?: {
+      /** Lines per replica, newest last. */
+      tail_lines?: number;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppLogsResponse_;
+  };
+  /**
+   * GET /apps/{app_id}/deployments/{deployment_id}/logs
+   * Get Deployment Logs
+   * tier: read · scope: apps:read
+   */
+  get_deployment_logs_apps__app_id__deployments__deployment_id__logs_get: {
+    input: {
+    path: {
+      app_id: string;
+      deployment_id: string;
+    };
+    query?: {
+      /** Lines per build step, newest last. */
+      tail_lines?: number;
+    };
+    headers?: {
+      "X-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AppLogsResponse_;
+  };
+}
+
+// 4 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_AppLogsResponse_ {
+  data: AppLogsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Logs for one app or one of its builds.
+ *
+ * ``redacted`` is always true and means only that graph8's credential patterns
+ * were applied. It is NOT a claim the output is safe to publish: these are a
+ * customer's own build and application logs, and an application can print a
+ * secret in a shape no pattern matches.
+ */
+export interface AppLogsResponse {
+  app_id: string;
+  containers?: Array<ContainerLogResponse>;
+  /** Set for build logs. `null` for the running app's logs. */
+  deployment_id?: string | null;
+  /** The app's own Kubernetes namespace. Derived from the app id, never supplied. */
+  namespace: string;
+  redacted?: boolean;
+  /** Lines requested per container, after clamping to the server maximum. */
+  tail_lines: number;
+}
+
+/**
+ * One container's tail of output.
+ *
+ * A build is five steps in one pod (fetch, scan-source, build, scan-image,
+ * push), so a single flat blob would leave a caller unable to say which step
+ * failed. ``kind`` separates the four init steps from the one container, which
+ * is the ordering Kubernetes actually runs them in.
+ */
+export interface ContainerLogResponse {
+  container: string;
+  kind: "init" | "container";
+  pod: string;
+  text: string;
+  /** The tail hit the per-container byte cap. Earlier output exists and was not returned. */
+  truncated?: boolean;
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}

package/docs/api/appLogs.md

@@ -0,0 +1,159 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.appLogs`: App Logs
+
+2 operations (2 read).
+
+2 of these also have a hand-written method (`g8.appPlatform`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [appLogs.d.ts](appLogs.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`getAppLogs`](#op-getapplogs) ★ | `GET /api/v1/apps/{app_id}/logs` | read | `apps:read` | Get App Logs |
+| [`getDeploymentLogs`](#op-getdeploymentlogs) ★ | `GET /api/v1/apps/{app_id}/deployments/{deployment_id}/logs` | read | `apps:read` | Get Deployment Logs |
+
+---
+
+<a id="op-getapplogs"></a>
+
+### `g8.api.appLogs.getAppLogs(input)`
+
+**Get App Logs**
+
+- HTTP: `GET /api/v1/apps/{app_id}/logs`
+- operationId: `get_app_logs_apps__app_id__logs_get` (also callable as `g8.api.call("get_app_logs_apps__app_id__logs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.logs()`](../sdk-clients.md#g8-appplatform-logs)
+
+What the running app is printing.
+
+The app's own pods only. The per-app egress proxy runs in the same namespace
+and is deliberately excluded: it is platform infrastructure that happens to
+live inside a tenant boundary, and its output is graph8's, not the builder's.
+
+Empty until a deployment reaches `deployed`. The `app` Deployment ships with
+`replicas: 0` and a pause image, so a namespace that exists still has no app
+pod to read until a build has been promoted.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `query.tail_lines` | `integer` | no | Lines per replica, newest last. default `200` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AppLogsResponse_`: the envelope `{ data: AppLogsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppLogsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `namespace` | `string` | yes | The app's own Kubernetes namespace. Derived from the app id, never supplied. |
+| `tail_lines` | `integer` | yes | Lines requested per container, after clamping to the server maximum. |
+| `containers` | `Array<ContainerLogResponse>` | no |  |
+| `deployment_id` | `string \| null` | no | Set for build logs. `null` for the running app's logs. |
+| `redacted` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.appLogs.getAppLogs({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-getdeploymentlogs"></a>
+
+### `g8.api.appLogs.getDeploymentLogs(input)`
+
+**Get Deployment Logs**
+
+- HTTP: `GET /api/v1/apps/{app_id}/deployments/{deployment_id}/logs`
+- operationId: `get_deployment_logs_apps__app_id__deployments__deployment_id__logs_get` (also callable as `g8.api.call("get_deployment_logs_apps__app_id__deployments__deployment_id__logs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.deploymentLogs()`](../sdk-clients.md#g8-appplatform-deploymentlogs)
+
+Why a build failed.
+
+Returns every step of the build pod in the order Kubernetes runs them --
+fetch, scan-source, build, scan-image, then push -- because "which step" is
+most of the answer. A step that has not started is omitted rather than
+returned empty, so a build in progress reports what exists so far.
+
+An empty `containers` list means the build pod is gone or was never created.
+Build pods are reaped an hour after they finish (`ttlSecondsAfterFinished`),
+so logs for an older deployment are genuinely unavailable rather than hidden;
+`last_error_sanitized` on the deployment is what survives.
+
+`redacted` is always true and means graph8's credential patterns were applied.
+It is NOT a claim the output is safe to publish: this is a customer's own
+build output and it can print a secret in a shape no pattern matches.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.deployment_id` | `string` | yes |  |
+| `query.tail_lines` | `integer` | no | Lines per build step, newest last. default `200` |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AppLogsResponse_`: the envelope `{ data: AppLogsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppLogsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `namespace` | `string` | yes | The app's own Kubernetes namespace. Derived from the app id, never supplied. |
+| `tail_lines` | `integer` | yes | Lines requested per container, after clamping to the server maximum. |
+| `containers` | `Array<ContainerLogResponse>` | no |  |
+| `deployment_id` | `string \| null` | no | Set for build logs. `null` for the running app's logs. |
+| `redacted` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.appLogs.getDeploymentLogs({ path: { app_id: "id", deployment_id: "id" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-containerlogresponse"></a>
+
+### `ContainerLogResponse`
+
+One container's tail of output. A build is five steps in one pod (fetch, scan-source, build, scan-image, push), so a single flat blob would leave a caller unable to say which step failed. ``kind`` separates the four init steps from the one container, which is the ordering Kubernetes actually runs them in.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `container` | `string` | yes |  |
+| `kind` | `"init" \| "container"` | yes |  |
+| `pod` | `string` | yes |  |
+| `text` | `string` | yes |  |
+| `truncated` | `boolean` | no | The tail hit the per-container byte cap. Earlier output exists and was not returned. default `false` |