@graph8/sdk 0.13.0 → 0.14.0

package/dist/index.js

@@ -23,9 +23,12 @@ __export(index_exports, {
   DEFAULT_APP_API: () => DEFAULT_APP_API,
   G8Error: () => G8Error,
   KNOWN_WEBHOOK_EVENTS: () => KNOWN_WEBHOOK_EVENTS,
+  MAX_TAIL_LINES: () => MAX_TAIL_LINES,
+  MIN_TAIL_LINES: () => MIN_TAIL_LINES,
   WebhookSignatureError: () => WebhookSignatureError,
   backoffDelayMs: () => backoffDelayMs,
   constructEvent: () => constructEvent,
+  createAppPlatformClient: () => createAppPlatformClient,
   createAppRequester: () => createAppRequester,
   createGraph8AppClient: () => createGraph8AppClient,
   createGraph8ServiceClient: () => createGraph8ServiceClient,
@@ -1258,10 +1261,284 @@ var createAppsClient = (apiKey, apiUrl) => {
   };
 };
 
-// src/fields.ts
+// src/appPlatform.ts
 var DEFAULT_API18 = "https://be.graph8.com";
-var createFieldsClient = (apiKey, apiUrl) => {
+var MIN_TAIL_LINES = 1;
+var MAX_TAIL_LINES = 2e3;
+var createAppPlatformClient = (apiKey, apiUrl) => {
   const baseUrl = apiUrl || DEFAULT_API18;
+  const unwrap = (resp) => resp.data ?? resp;
+  return {
+    // ---- source binding -------------------------------------------------
+    /**
+     * 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.
+     */
+    async setSource(appId, params) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/source`,
+        apiKey,
+        {
+          method: "PUT",
+          body: {
+            repo_url: params.repo_url,
+            provider: params.provider,
+            default_branch: params.default_branch ?? null,
+            credential_ref: params.credential_ref ?? null
+          }
+        }
+      );
+      return unwrap(resp);
+    },
+    /** Unbind the source. Returns the full app with every source field null. */
+    async clearSource(appId) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/source`,
+        apiKey,
+        { method: "DELETE" }
+      );
+      return unwrap(resp);
+    },
+    // ---- deployments ----------------------------------------------------
+    /** Every deployment for this app, newest first. Never 404s for an app with none. */
+    async listDeployments(appId) {
+      return request(baseUrl, `/api/v1/apps/${appId}/deployments`, apiKey);
+    },
+    /**
+     * 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.
+     */
+    async deploy(appId, params) {
+      const body = { source_ref: params.source_ref };
+      if (params.schema_version_id) body.schema_version_id = params.schema_version_id;
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/deployments`,
+        apiKey,
+        { method: "POST", body }
+      );
+      return unwrap(resp);
+    },
+    /** Fetch one deployment. The polling endpoint for a build loop. */
+    async getDeployment(appId, deploymentId) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/deployments/${deploymentId}`,
+        apiKey
+      );
+      return unwrap(resp);
+    },
+    /**
+     * 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".
+     */
+    async activeDeployment(appId) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/deployments/active`,
+        apiKey
+      );
+      return resp.data ?? 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.
+     */
+    async promote(appId, deploymentId, imageDigest) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/deployments/${deploymentId}/promote`,
+        apiKey,
+        { method: "POST", body: { image_digest: imageDigest } }
+      );
+      return unwrap(resp);
+    },
+    /** Roll back a deployment that is currently serving. Only a `deployed` one may be. */
+    async rollback(appId, deploymentId) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/deployments/${deploymentId}/rollback`,
+        apiKey,
+        { method: "POST", body: {} }
+      );
+      return unwrap(resp);
+    },
+    // ---- logs -----------------------------------------------------------
+    /**
+     * 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.
+     */
+    async deploymentLogs(appId, deploymentId, tailLines) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/deployments/${deploymentId}/logs`,
+        apiKey,
+        { query: tailLines === void 0 ? void 0 : { tail_lines: tailLines } }
+      );
+      return unwrap(resp);
+    },
+    /**
+     * 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`.
+     */
+    async logs(appId, tailLines) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/logs`,
+        apiKey,
+        { query: tailLines === void 0 ? void 0 : { tail_lines: tailLines } }
+      );
+      return unwrap(resp);
+    },
+    // ---- domains --------------------------------------------------------
+    /** Every hostname claimed for this app, whatever its verification state. */
+    async listDomains(appId) {
+      return request(baseUrl, `/api/v1/apps/${appId}/domains`, apiKey);
+    },
+    /**
+     * 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.
+     */
+    async claimDomain(appId, hostname) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/domains`,
+        apiKey,
+        { method: "POST", body: { hostname } }
+      );
+      return unwrap(resp);
+    },
+    /**
+     * 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.
+     */
+    async verifyDomain(appId, hostname) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/domains/${encodeURIComponent(hostname)}/verify`,
+        apiKey,
+        { method: "POST", body: {} }
+      );
+      return unwrap(resp);
+    },
+    /**
+     * 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.
+     */
+    async releaseDomain(appId, hostname) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/domains/${encodeURIComponent(hostname)}`,
+        apiKey,
+        { method: "DELETE" }
+      );
+      return unwrap(resp);
+    },
+    // ---- secrets --------------------------------------------------------
+    /**
+     * 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.
+     */
+    async listSecrets(appId) {
+      return request(baseUrl, `/api/v1/apps/${appId}/secrets`, apiKey);
+    },
+    /**
+     * 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.
+     */
+    async putSecret(appId, secretKey, providerRef) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/secrets/${encodeURIComponent(secretKey)}`,
+        apiKey,
+        { method: "PUT", body: { provider_ref: providerRef ?? null } }
+      );
+      return unwrap(resp);
+    },
+    /** Undeclare a secret. A key the app never declared is a 404, so a typo is
+     *  never reported as a successful removal. */
+    async deleteSecret(appId, secretKey) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/secrets/${encodeURIComponent(secretKey)}`,
+        apiKey,
+        { method: "DELETE" }
+      );
+      return unwrap(resp);
+    },
+    // ---- schema versions ------------------------------------------------
+    /**
+     * 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.
+     */
+    async publishSchemaVersion(appId, objects) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/apps/${appId}/schema-versions`,
+        apiKey,
+        { method: "POST", body: { objects } }
+      );
+      return unwrap(resp);
+    },
+    /** Every schema version this app has published. Empty array, never 404. */
+    async listSchemaVersions(appId) {
+      return request(baseUrl, `/api/v1/apps/${appId}/schema-versions`, apiKey);
+    }
+  };
+};
+
+// src/fields.ts
+var DEFAULT_API19 = "https://be.graph8.com";
+var createFieldsClient = (apiKey, apiUrl) => {
+  const baseUrl = apiUrl || DEFAULT_API19;
   return {
     /** List contact fields (base + custom). Pass listId to include list-specific custom fields. */
     async listContactFields(listId) {
@@ -1303,9 +1580,9 @@ var createFieldsClient = (apiKey, apiUrl) => {
 };
 
 // src/objects.ts
-var DEFAULT_API19 = "https://be.graph8.com";
+var DEFAULT_API20 = "https://be.graph8.com";
 var createObjectsClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API19;
+  const baseUrl = apiUrl || DEFAULT_API20;
   const encode = (value) => encodeURIComponent(value);
   return {
     /** List the custom object types in your workspace. */
@@ -1366,12 +1643,12 @@ var createObjectsClient = (apiKey, apiUrl) => {
      * Values are versioned rather than overwritten, so the previous value stays
      * readable through `history`.
      */
-    async updateRecord(objectSlug, recordId, values) {
+    async updateRecord(objectSlug, recordId, values, options) {
       const resp = await request(
         baseUrl,
         `/api/v1/objects/${encode(objectSlug)}/records/${encode(recordId)}`,
         apiKey,
-        { method: "PATCH", body: { values } }
+        { method: "PATCH", body: { values, ...options?.expectedRevision === void 0 ? {} : { expected_revision: options.expectedRevision } } }
       );
       return resp.data ?? resp;
     },
@@ -1388,6 +1665,16 @@ var createObjectsClient = (apiKey, apiUrl) => {
       );
       return resp.data ?? resp;
     },
+    /** Restore archived values under current constraints. Conflicts leave the record archived. */
+    async restoreRecord(objectSlug, recordId) {
+      const resp = await request(
+        baseUrl,
+        `/api/v1/objects/${encode(objectSlug)}/records/${encode(recordId)}/restore`,
+        apiKey,
+        { method: "POST" }
+      );
+      return resp.data ?? resp;
+    },
     /**
      * A record's value timeline, newest first. An entry whose `active_until` is
      * null is the value currently in force.
@@ -1405,9 +1692,9 @@ var createObjectsClient = (apiKey, apiUrl) => {
 };
 
 // src/deals.ts
-var DEFAULT_API20 = "https://be.graph8.com";
+var DEFAULT_API21 = "https://be.graph8.com";
 var createDealsClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API20;
+  const baseUrl = apiUrl || DEFAULT_API21;
   return {
     /** List all deal pipelines and their stages. */
     async pipelines() {
@@ -1451,9 +1738,9 @@ var createDealsClient = (apiKey, apiUrl) => {
 };
 
 // src/inbox.ts
-var DEFAULT_API21 = "https://be.graph8.com";
+var DEFAULT_API22 = "https://be.graph8.com";
 var createInboxClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API21;
+  const baseUrl = apiUrl || DEFAULT_API22;
   return {
     /** List inbox threads across email, SMS, and LinkedIn. */
     async list(params = {}) {
@@ -1506,9 +1793,9 @@ var createInboxClient = (apiKey, apiUrl) => {
 };
 
 // src/quotes.ts
-var DEFAULT_API22 = "https://be.graph8.com";
+var DEFAULT_API23 = "https://be.graph8.com";
 var createQuotesClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API22;
+  const baseUrl = apiUrl || DEFAULT_API23;
   return {
     /** List quotes org-wide with optional filters and pagination. */
     async list(params = {}) {
@@ -1580,9 +1867,9 @@ var createQuotesClient = (apiKey, apiUrl) => {
 };
 
 // src/pipelines.ts
-var DEFAULT_API23 = "https://be.graph8.com";
+var DEFAULT_API24 = "https://be.graph8.com";
 var createPipelinesClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API23;
+  const baseUrl = apiUrl || DEFAULT_API24;
   return {
     /** List all stage-checklist pipelines with stages, evidence, scripts. */
     async list() {
@@ -1664,9 +1951,9 @@ var createPipelinesClient = (apiKey, apiUrl) => {
 };
 
 // src/workflows.ts
-var DEFAULT_API24 = "https://be.graph8.com";
+var DEFAULT_API25 = "https://be.graph8.com";
 var createWorkflowsClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API24;
+  const baseUrl = apiUrl || DEFAULT_API25;
   return {
     /** List workflows org-wide. */
     async list(params = {}) {
@@ -1782,9 +2069,9 @@ var createWorkflowsClient = (apiKey, apiUrl) => {
 };
 
 // src/skills.ts
-var DEFAULT_API25 = "https://be.graph8.com";
+var DEFAULT_API26 = "https://be.graph8.com";
 var createSkillsClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API25;
+  const baseUrl = apiUrl || DEFAULT_API26;
   return {
     /** List skills. */
     async list(params = {}) {
@@ -1871,9 +2158,9 @@ var createSkillsClient = (apiKey, apiUrl) => {
 };
 
 // src/intent.ts
-var DEFAULT_API26 = "https://be.graph8.com";
+var DEFAULT_API27 = "https://be.graph8.com";
 var createIntentClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API26;
+  const baseUrl = apiUrl || DEFAULT_API27;
   const get = (path) => request(baseUrl, `/api/v1${path}`, apiKey);
   const post = (path, body = {}) => request(baseUrl, `/api/v1${path}`, apiKey, { method: "POST", body });
   const del = (path) => request(baseUrl, `/api/v1${path}`, apiKey, { method: "DELETE" });
@@ -1948,9 +2235,9 @@ var createIntentClient = (apiKey, apiUrl) => {
 };
 
 // src/studio.ts
-var DEFAULT_API27 = "https://be.graph8.com";
+var DEFAULT_API28 = "https://be.graph8.com";
 var createStudioClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API27;
+  const baseUrl = apiUrl || DEFAULT_API28;
   const get = (path, params = {}) => request(baseUrl, `/api/v1${path}`, apiKey, { query: params });
   const post = (path, body = {}) => request(baseUrl, `/api/v1${path}`, apiKey, { method: "POST", body });
   const patch = (path, body = {}) => request(baseUrl, `/api/v1${path}`, apiKey, { method: "PATCH", body });
@@ -2005,9 +2292,9 @@ var createStudioClient = (apiKey, apiUrl) => {
 };
 
 // src/meetings.ts
-var DEFAULT_API28 = "https://be.graph8.com";
+var DEFAULT_API29 = "https://be.graph8.com";
 var createMeetingsClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API28;
+  const baseUrl = apiUrl || DEFAULT_API29;
   return {
     /** List meetings with optional filters. Returns summary rows without transcript / analysis. */
     async list(params = {}) {
@@ -2022,9 +2309,9 @@ var createMeetingsClient = (apiKey, apiUrl) => {
 };
 
 // src/audiences.ts
-var DEFAULT_API29 = "https://be.graph8.com";
+var DEFAULT_API30 = "https://be.graph8.com";
 var createAudiencesClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API29;
+  const baseUrl = apiUrl || DEFAULT_API30;
   const base = "/api/v1/audience-syncs";
   return {
     /** List all audience syncs for the organization. */
@@ -2072,9 +2359,9 @@ var createAudiencesClient = (apiKey, apiUrl) => {
 };
 
 // src/search.ts
-var DEFAULT_API30 = "https://be.graph8.com";
+var DEFAULT_API31 = "https://be.graph8.com";
 var createSearchClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API30;
+  const baseUrl = apiUrl || DEFAULT_API31;
   const body = (p) => ({ filters: [], page: 1, limit: 25, ...p });
   return {
     /** Search open-data contacts by filter. */
@@ -2105,9 +2392,9 @@ var createSearchClient = (apiKey, apiUrl) => {
 };
 
 // src/agency.ts
-var DEFAULT_API31 = "https://be.graph8.com";
+var DEFAULT_API32 = "https://be.graph8.com";
 var createAgencyClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API31;
+  const baseUrl = apiUrl || DEFAULT_API32;
   return {
     /** Describe the agency credential: agency org + authorized client count. */
     async me() {
@@ -2122,9 +2409,9 @@ var createAgencyClient = (apiKey, apiUrl) => {
 };
 
 // src/marketplace.ts
-var DEFAULT_API32 = "https://be.graph8.com";
+var DEFAULT_API33 = "https://be.graph8.com";
 var createMarketplaceClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API32;
+  const baseUrl = apiUrl || DEFAULT_API33;
   const base = "/api/v1/marketplace";
   return {
     /** Your own marketplace SDR profile. */
@@ -2174,9 +2461,9 @@ var createMarketplaceClient = (apiKey, apiUrl) => {
 };
 
 // src/snippet.ts
-var DEFAULT_API33 = "https://be.graph8.com";
+var DEFAULT_API34 = "https://be.graph8.com";
 var createSnippetClient = (apiKey, apiUrl) => {
-  const baseUrl = apiUrl || DEFAULT_API33;
+  const baseUrl = apiUrl || DEFAULT_API34;
   return {
     /** Get your org's tracking snippet (write key + React/script-tag embeds + config). */
     async get() {
@@ -2188,7 +2475,7 @@ var createSnippetClient = (apiKey, apiUrl) => {
 
 // src/core.ts
 var DEFAULT_HOST = "https://t.graph8.com";
-var DEFAULT_API34 = "https://be.graph8.com";
+var DEFAULT_API35 = "https://be.graph8.com";
 var G8 = class {
   constructor() {
     /** @internal */
@@ -2232,6 +2519,8 @@ var G8 = class {
     /** @internal */
     this._apps = null;
     /** @internal */
+    this._appPlatform = null;
+    /** @internal */
     this._objects = null;
     /** @internal */
     this._deals = null;
@@ -2275,7 +2564,7 @@ var G8 = class {
         debug: config.debug
       });
     }
-    const apiUrl = config.apiUrl || DEFAULT_API34;
+    const apiUrl = config.apiUrl || DEFAULT_API35;
     const writeKey = config.writeKey || "";
     const apiKey = config.apiKey || "";
     if (writeKey) {
@@ -2299,6 +2588,7 @@ var G8 = class {
       this._tasks = createTasksClient(apiKey, apiUrl);
       this._fields = createFieldsClient(apiKey, apiUrl);
       this._apps = createAppsClient(apiKey, apiUrl);
+      this._appPlatform = createAppPlatformClient(apiKey, apiUrl);
       this._objects = createObjectsClient(apiKey, apiUrl);
       this._deals = createDealsClient(apiKey, apiUrl);
       this._inbox = createInboxClient(apiKey, apiUrl);
@@ -2425,6 +2715,18 @@ var G8 = class {
     this._assertKey("apps");
     return this._apps;
   }
+  /**
+   * Ship a hosted app: bind a source, deploy, promote, attach a hostname, read
+   * build logs (requires API key). PREVIEW.
+   *
+   * Separate from `apps` on purpose. `apps` is the app's IDENTITY -- create it,
+   * see who installed it, what it cost. This is its LIFECYCLE, and the two have
+   * different blast radii: a mistake here takes a customer's app down.
+   */
+  get appPlatform() {
+    this._assertKey("appPlatform");
+    return this._appPlatform;
+  }
   /** Custom object types, their schema, and their records (requires API key). PREVIEW. */
   get objects() {
     this._assertKey("objects");
@@ -2682,9 +2984,12 @@ function createGraph8ServiceClient(config) {
   DEFAULT_APP_API,
   G8Error,
   KNOWN_WEBHOOK_EVENTS,
+  MAX_TAIL_LINES,
+  MIN_TAIL_LINES,
   WebhookSignatureError,
   backoffDelayMs,
   constructEvent,
+  createAppPlatformClient,
   createAppRequester,
   createGraph8AppClient,
   createGraph8ServiceClient,