deepline 0.3.89 → 0.3.91

package/dist/index.js

@@ -94,6 +94,26 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/pagination.ts
+async function* iterateCursorPages(fetchPage) {
+  let cursor = null;
+  const seen = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const page = await fetchPage(cursor);
+    if (page.hasMore) {
+      if (!page.cursor || seen.has(page.cursor)) {
+        throw new Error(
+          "Pagination reported more results without an advancing cursor"
+        );
+      }
+      seen.add(page.cursor);
+    }
+    yield page.items;
+    if (!page.hasMore) return;
+    cursor = page.cursor;
+  }
+}
+
 // src/config.ts
 var import_node_fs = require("fs");
 var import_node_os = require("os");
@@ -835,20 +855,22 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.89",
-  updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
+  // 0.3.90 is the first deliberately versioned SDK release for API v3.
+  version: "0.3.91",
+  updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
   },
   contracts: {
     api: {
       name: "sdk-http-api",
-      // API v2 is append-only. A breaking public request/response change needs
-      // v3 and an explicit v2 support-window decision, never a patch release.
-      currentMajor: 2,
-      supportedMajors: [2],
-      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      // Concise Play grep has the current wire id. Older ids follow the
+      // standard API support window.
+      currentMajor: 3,
+      supportedMajors: [3, 2],
+      // Older ids remain subject to the API support window.
       legacyWireIds: [
+        "2026-09-play-grep-concise-results",
         "2026-07-admin-cli-local-cutover",
         "2026-07-native-monitor-launch-hard-cutover"
       ]
@@ -2063,6 +2085,10 @@ function normalizeProductNotificationEmail(value) {
   const email = typeof value === "string" ? value.trim().toLowerCase() : "";
   return email && email.length <= 320 && PRODUCT_NOTIFICATION_EMAIL_PATTERN.test(email) ? email : null;
 }
+var DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING = {
+  mode: "rolling_limit",
+  windowMs: 36e5
+};
 
 // src/stream-reconnect.ts
 var STREAM_RECONNECT_BASE_DELAY_MS = 500;
@@ -4556,6 +4582,7 @@ var DeeplineClient = class {
     this.runs = {
       get: (runId, options2) => this.getRunStatus(runId, options2),
       list: (options2) => this.listRuns(options2),
+      listPage: (options2) => this.listRunsPage(options2),
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
       input: (runId) => this.getRunInput(runId),
@@ -4581,9 +4608,19 @@ var DeeplineClient = class {
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
         get: () => this.getTargetAutoRecharge(),
+        trigger: (options2) => this.http.post(
+          "/api/v2/billing/auto-recharge/trigger",
+          {},
+          {
+            "Idempotency-Key": requireTargetBillingIdempotencyKey(
+              options2?.idempotencyKey ?? globalThis.crypto.randomUUID()
+            )
+          }
+        ),
         update: (options2) => this.updateTargetAutoRecharge(options2)
       },
       purchaseCredits: (options2) => this.purchaseTargetBillingCredits(options2),
+      recoverCreditPurchase: (options2) => this.recoverTargetBillingCreditPurchase(options2),
       transitionPlan: (options2) => this.transitionTargetBillingPlan(options2),
       portalSession: () => this.createTargetBillingPortalSession()
     };
@@ -4752,6 +4789,14 @@ var DeeplineClient = class {
     if (options.playName !== void 0) params.set("play", options.playName);
     return this.http.get(`/api/v2/secrets?${params.toString()}`);
   }
+  /** Add, replace, or clear the non-sensitive note attached to one secret. */
+  async updateSecretNote(secretId, note) {
+    const response = await this.http.patch(
+      `/api/v2/secrets/${encodeURIComponent(secretId)}`,
+      { note }
+    );
+    return response.secret;
+  }
   // ——————————————————————————————————————————————————————————
   // Tools
   // ——————————————————————————————————————————————————————————
@@ -5769,6 +5814,10 @@ var DeeplineClient = class {
    * ```
    */
   async listRuns(options) {
+    return (await this.listRunsPage(options)).runs;
+  }
+  /** Read one run page without discarding server pagination metadata. */
+  async listRunsPage(options) {
     const playName = options.play?.trim();
     const params = new URLSearchParams();
     if (playName) {
@@ -5799,7 +5848,7 @@ var DeeplineClient = class {
     const response = await this.http.get(
       `/api/v2/runs?${params.toString()}`
     );
-    return response.runs ?? [];
+    return { ...response, runs: response.runs ?? [] };
   }
   /**
    * Observe one run's live events. Uses the Convex Run Snapshot subscription
@@ -6194,13 +6243,33 @@ var DeeplineClient = class {
     );
   }
   /**
-   * List callable plays visible to the workspace.
+   * List one page of callable plays; grep retains exhaustive matching results.
+   * Use listPlaysPage to retain pagination metadata.
    *
    * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
    * `origin: "owned"` for org-owned plays.
    */
   async listPlays(options) {
+    if (!options?.grep?.trim()) {
+      return (await this.requestPlaysPage(options, false)).plays;
+    }
+    const plays = [];
+    for await (const items of iterateCursorPages(async (cursor) => {
+      const page = await this.listPlaysPage({ ...options, cursor });
+      return { items: page.plays, cursor: page.cursor, hasMore: page.hasMore };
+    })) {
+      plays.push(...items);
+    }
+    return plays;
+  }
+  /** Read one bounded inventory page; cursor continues the same filters. */
+  async listPlaysPage(options) {
+    return this.requestPlaysPage(options);
+  }
+  async requestPlaysPage(options, paginateInventory = true) {
     const params = new URLSearchParams();
+    if (paginateInventory && !options?.grep?.trim())
+      params.set("inventory_paginated", "1");
     if (options?.origin) params.set("origin", options.origin);
     if (options?.categories) {
       params.set(
@@ -6212,26 +6281,27 @@ var DeeplineClient = class {
       params.set("include_tool_categories", "1");
     }
     if (options?.includeArchived) params.set("include_archived", "1");
+    if (options?.includeCostEstimates) {
+      params.set("include_cost_estimates", "1");
+    }
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
-      params.set("grep_mode", options.grepMode ?? "all");
-      params.set("grep_paginated", "1");
       params.set("limit", "60");
     }
-    const plays = [];
-    let cursor = null;
-    let hasMore = true;
-    do {
-      if (cursor) params.set("cursor", cursor);
-      const suffix = params.toString() ? `?${params.toString()}` : "";
-      const response = await this.http.get(
-        `/api/v2/plays${suffix}`
-      );
-      plays.push(...response.plays ?? []);
-      cursor = response.pagination?.cursor ?? response.cursor ?? null;
-      hasMore = Boolean(response.pagination?.hasMore ?? response.hasMore);
-    } while (Boolean(options?.grep?.trim()) && hasMore && cursor);
-    return plays;
+    if (options?.limit !== void 0) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error("Play page limit must be a positive integer");
+      }
+      params.set("limit", String(options.limit));
+    }
+    if (options?.cursor) params.set("cursor", options.cursor);
+    const suffix = params.size ? `?${params.toString()}` : "";
+    const response = await this.http.get(`/api/v2/plays${suffix}`);
+    return {
+      plays: response.plays ?? [],
+      cursor: response.pagination?.cursor ?? response.cursor ?? null,
+      hasMore: Boolean(response.pagination?.hasMore ?? response.hasMore)
+    };
   }
   /** Set whether an org-owned Play sorts before unpinned Plays. */
   async setPlayPinned(playName, pinned) {
@@ -6365,7 +6435,7 @@ var DeeplineClient = class {
       groupKey,
       name,
       enabled: true,
-      deliveryTiming: { mode: "immediate" },
+      deliveryTiming: DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
       source: "workspace",
       configMode: "custom",
       version: 0
@@ -6920,7 +6990,8 @@ var DeeplineClient = class {
       options.enabled ? {
         enabled: true,
         threshold_credits: options.thresholdCredits,
-        refill_to_credits: options.refillToCredits
+        refill_to_credits: options.refillToCredits,
+        ...options.purchaseLimitCents !== void 0 ? { purchase_limit_cents: options.purchaseLimitCents } : {}
       } : { enabled: false },
       { "Idempotency-Key": idempotencyKey }
     );
@@ -6941,6 +7012,39 @@ var DeeplineClient = class {
       { maxRetries: 0, exactUrlOnly: true }
     );
   }
+  /** Recover only the original workspace, credit amount, and purchase key; never charge. */
+  async recoverTargetBillingCreditPurchase(options) {
+    if (typeof options.idempotencyKey !== "string") {
+      throw new DeeplineError(
+        "The original billing idempotencyKey is required.",
+        void 0,
+        "INVALID_BILLING_IDEMPOTENCY_KEY"
+      );
+    }
+    const idempotencyKey = requireTargetBillingIdempotencyKey(
+      options.idempotencyKey
+    );
+    if (!Number.isSafeInteger(options.credits) || options.credits <= 0) {
+      throw new DeeplineError(
+        "credits must be a positive safe integer.",
+        void 0,
+        "INVALID_CREDITS"
+      );
+    }
+    if (typeof options.orgId !== "string" || !options.orgId.trim() || options.orgId !== options.orgId.trim()) {
+      throw new DeeplineError(
+        "The original orgId is required without surrounding whitespace.",
+        void 0,
+        "INVALID_ORG_ID"
+      );
+    }
+    return this.http.post(
+      "/api/v2/billing/credit-purchases/recover",
+      { credits: options.credits, org_id: options.orgId },
+      { "Idempotency-Key": idempotencyKey },
+      { maxRetries: 0, exactUrlOnly: true }
+    );
+  }
   /**
    * Start, change, cancel, or restore a target plan through one idempotent
    * commercial operation.
@@ -11135,7 +11239,7 @@ function defineMonitor(definition) {
   return definition;
 }
 
-// src/monitor-fleet-contract.ts
+// ../integration-contracts/monitor-fleet-contract.ts
 var MONITOR_FLEET_MAX_MEMBERS = 1e3;
 var MONITOR_FLEET_FRONTIER_MAX_ROWS = 1e4;
 var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1;

package/dist/index.mjs

@@ -1,3 +1,23 @@
+// src/pagination.ts
+async function* iterateCursorPages(fetchPage) {
+  let cursor = null;
+  const seen = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const page = await fetchPage(cursor);
+    if (page.hasMore) {
+      if (!page.cursor || seen.has(page.cursor)) {
+        throw new Error(
+          "Pagination reported more results without an advancing cursor"
+        );
+      }
+      seen.add(page.cursor);
+    }
+    yield page.items;
+    if (!page.hasMore) return;
+    cursor = page.cursor;
+  }
+}
+
 // src/config.ts
 import {
   existsSync,
@@ -747,20 +767,22 @@ var SDK_RELEASE = {
   // available at toolResponse.rawV2 while toolResponse.raw and all declared
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
-  version: "0.3.89",
-  updateSummary: "Automatic CLI updates are now enabled by default. To opt out, run `deepline settings autoupdate off`; use `deepline settings autoupdate on` to re-enable updates or `deepline settings autoupdate pin <version>` to hold an exact release. This release also adds raw-v2 tool responses at toolResponse.rawV2 while preserving existing toolResponse.raw and declared getters.",
+  // 0.3.90 is the first deliberately versioned SDK release for API v3.
+  version: "0.3.91",
+  updateSummary: "Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.",
   packageCapabilities: {
     updatePreferences: 1
   },
   contracts: {
     api: {
       name: "sdk-http-api",
-      // API v2 is append-only. A breaking public request/response change needs
-      // v3 and an explicit v2 support-window decision, never a patch release.
-      currentMajor: 2,
-      supportedMajors: [2],
-      // Accepted only to bridge SDKs released before X-Deepline-API-Major.
+      // Concise Play grep has the current wire id. Older ids follow the
+      // standard API support window.
+      currentMajor: 3,
+      supportedMajors: [3, 2],
+      // Older ids remain subject to the API support window.
       legacyWireIds: [
+        "2026-09-play-grep-concise-results",
         "2026-07-admin-cli-local-cutover",
         "2026-07-native-monitor-launch-hard-cutover"
       ]
@@ -1975,6 +1997,10 @@ function normalizeProductNotificationEmail(value) {
   const email = typeof value === "string" ? value.trim().toLowerCase() : "";
   return email && email.length <= 320 && PRODUCT_NOTIFICATION_EMAIL_PATTERN.test(email) ? email : null;
 }
+var DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING = {
+  mode: "rolling_limit",
+  windowMs: 36e5
+};
 
 // src/stream-reconnect.ts
 var STREAM_RECONNECT_BASE_DELAY_MS = 500;
@@ -4468,6 +4494,7 @@ var DeeplineClient = class {
     this.runs = {
       get: (runId, options2) => this.getRunStatus(runId, options2),
       list: (options2) => this.listRuns(options2),
+      listPage: (options2) => this.listRunsPage(options2),
       tail: (runId, options2) => this.tailRun(runId, options2),
       logs: (runId, options2) => this.getRunLogs(runId, options2),
       input: (runId) => this.getRunInput(runId),
@@ -4493,9 +4520,19 @@ var DeeplineClient = class {
       targetStatus: () => this.getTargetBillingStatus(),
       autoRecharge: {
         get: () => this.getTargetAutoRecharge(),
+        trigger: (options2) => this.http.post(
+          "/api/v2/billing/auto-recharge/trigger",
+          {},
+          {
+            "Idempotency-Key": requireTargetBillingIdempotencyKey(
+              options2?.idempotencyKey ?? globalThis.crypto.randomUUID()
+            )
+          }
+        ),
         update: (options2) => this.updateTargetAutoRecharge(options2)
       },
       purchaseCredits: (options2) => this.purchaseTargetBillingCredits(options2),
+      recoverCreditPurchase: (options2) => this.recoverTargetBillingCreditPurchase(options2),
       transitionPlan: (options2) => this.transitionTargetBillingPlan(options2),
       portalSession: () => this.createTargetBillingPortalSession()
     };
@@ -4664,6 +4701,14 @@ var DeeplineClient = class {
     if (options.playName !== void 0) params.set("play", options.playName);
     return this.http.get(`/api/v2/secrets?${params.toString()}`);
   }
+  /** Add, replace, or clear the non-sensitive note attached to one secret. */
+  async updateSecretNote(secretId, note) {
+    const response = await this.http.patch(
+      `/api/v2/secrets/${encodeURIComponent(secretId)}`,
+      { note }
+    );
+    return response.secret;
+  }
   // ——————————————————————————————————————————————————————————
   // Tools
   // ——————————————————————————————————————————————————————————
@@ -5681,6 +5726,10 @@ var DeeplineClient = class {
    * ```
    */
   async listRuns(options) {
+    return (await this.listRunsPage(options)).runs;
+  }
+  /** Read one run page without discarding server pagination metadata. */
+  async listRunsPage(options) {
     const playName = options.play?.trim();
     const params = new URLSearchParams();
     if (playName) {
@@ -5711,7 +5760,7 @@ var DeeplineClient = class {
     const response = await this.http.get(
       `/api/v2/runs?${params.toString()}`
     );
-    return response.runs ?? [];
+    return { ...response, runs: response.runs ?? [] };
   }
   /**
    * Observe one run's live events. Uses the Convex Run Snapshot subscription
@@ -6106,13 +6155,33 @@ var DeeplineClient = class {
     );
   }
   /**
-   * List callable plays visible to the workspace.
+   * List one page of callable plays; grep retains exhaustive matching results.
+   * Use listPlaysPage to retain pagination metadata.
    *
    * Pass `origin: "prebuilt"` for Deepline-managed prebuilts or
    * `origin: "owned"` for org-owned plays.
    */
   async listPlays(options) {
+    if (!options?.grep?.trim()) {
+      return (await this.requestPlaysPage(options, false)).plays;
+    }
+    const plays = [];
+    for await (const items of iterateCursorPages(async (cursor) => {
+      const page = await this.listPlaysPage({ ...options, cursor });
+      return { items: page.plays, cursor: page.cursor, hasMore: page.hasMore };
+    })) {
+      plays.push(...items);
+    }
+    return plays;
+  }
+  /** Read one bounded inventory page; cursor continues the same filters. */
+  async listPlaysPage(options) {
+    return this.requestPlaysPage(options);
+  }
+  async requestPlaysPage(options, paginateInventory = true) {
     const params = new URLSearchParams();
+    if (paginateInventory && !options?.grep?.trim())
+      params.set("inventory_paginated", "1");
     if (options?.origin) params.set("origin", options.origin);
     if (options?.categories) {
       params.set(
@@ -6124,26 +6193,27 @@ var DeeplineClient = class {
       params.set("include_tool_categories", "1");
     }
     if (options?.includeArchived) params.set("include_archived", "1");
+    if (options?.includeCostEstimates) {
+      params.set("include_cost_estimates", "1");
+    }
     if (options?.grep?.trim()) {
       params.set("grep", options.grep.trim());
-      params.set("grep_mode", options.grepMode ?? "all");
-      params.set("grep_paginated", "1");
       params.set("limit", "60");
     }
-    const plays = [];
-    let cursor = null;
-    let hasMore = true;
-    do {
-      if (cursor) params.set("cursor", cursor);
-      const suffix = params.toString() ? `?${params.toString()}` : "";
-      const response = await this.http.get(
-        `/api/v2/plays${suffix}`
-      );
-      plays.push(...response.plays ?? []);
-      cursor = response.pagination?.cursor ?? response.cursor ?? null;
-      hasMore = Boolean(response.pagination?.hasMore ?? response.hasMore);
-    } while (Boolean(options?.grep?.trim()) && hasMore && cursor);
-    return plays;
+    if (options?.limit !== void 0) {
+      if (!Number.isSafeInteger(options.limit) || options.limit < 1) {
+        throw new Error("Play page limit must be a positive integer");
+      }
+      params.set("limit", String(options.limit));
+    }
+    if (options?.cursor) params.set("cursor", options.cursor);
+    const suffix = params.size ? `?${params.toString()}` : "";
+    const response = await this.http.get(`/api/v2/plays${suffix}`);
+    return {
+      plays: response.plays ?? [],
+      cursor: response.pagination?.cursor ?? response.cursor ?? null,
+      hasMore: Boolean(response.pagination?.hasMore ?? response.hasMore)
+    };
   }
   /** Set whether an org-owned Play sorts before unpinned Plays. */
   async setPlayPinned(playName, pinned) {
@@ -6277,7 +6347,7 @@ var DeeplineClient = class {
       groupKey,
       name,
       enabled: true,
-      deliveryTiming: { mode: "immediate" },
+      deliveryTiming: DEFAULT_PRODUCT_NOTIFICATION_DELIVERY_TIMING,
       source: "workspace",
       configMode: "custom",
       version: 0
@@ -6832,7 +6902,8 @@ var DeeplineClient = class {
       options.enabled ? {
         enabled: true,
         threshold_credits: options.thresholdCredits,
-        refill_to_credits: options.refillToCredits
+        refill_to_credits: options.refillToCredits,
+        ...options.purchaseLimitCents !== void 0 ? { purchase_limit_cents: options.purchaseLimitCents } : {}
       } : { enabled: false },
       { "Idempotency-Key": idempotencyKey }
     );
@@ -6853,6 +6924,39 @@ var DeeplineClient = class {
       { maxRetries: 0, exactUrlOnly: true }
     );
   }
+  /** Recover only the original workspace, credit amount, and purchase key; never charge. */
+  async recoverTargetBillingCreditPurchase(options) {
+    if (typeof options.idempotencyKey !== "string") {
+      throw new DeeplineError(
+        "The original billing idempotencyKey is required.",
+        void 0,
+        "INVALID_BILLING_IDEMPOTENCY_KEY"
+      );
+    }
+    const idempotencyKey = requireTargetBillingIdempotencyKey(
+      options.idempotencyKey
+    );
+    if (!Number.isSafeInteger(options.credits) || options.credits <= 0) {
+      throw new DeeplineError(
+        "credits must be a positive safe integer.",
+        void 0,
+        "INVALID_CREDITS"
+      );
+    }
+    if (typeof options.orgId !== "string" || !options.orgId.trim() || options.orgId !== options.orgId.trim()) {
+      throw new DeeplineError(
+        "The original orgId is required without surrounding whitespace.",
+        void 0,
+        "INVALID_ORG_ID"
+      );
+    }
+    return this.http.post(
+      "/api/v2/billing/credit-purchases/recover",
+      { credits: options.credits, org_id: options.orgId },
+      { "Idempotency-Key": idempotencyKey },
+      { maxRetries: 0, exactUrlOnly: true }
+    );
+  }
   /**
    * Start, change, cancel, or restore a target plan through one idempotent
    * commercial operation.
@@ -11047,7 +11151,7 @@ function defineMonitor(definition) {
   return definition;
 }
 
-// src/monitor-fleet-contract.ts
+// ../integration-contracts/monitor-fleet-contract.ts
 var MONITOR_FLEET_MAX_MEMBERS = 1e3;
 var MONITOR_FLEET_FRONTIER_MAX_ROWS = 1e4;
 var MONITOR_FLEET_AUTHORING_CONTRACT_EDITION = 1;