@pipe0/client 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pipe0/client
 
+## 1.0.2
+
+### Patch Changes
+
+- 1c4d867: Add rate limits
+
+## 1.0.1
+
+### Patch Changes
+
+- 75012eb: Fix template syntax
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -59,20 +59,37 @@ const data = await piper.searches.search({
   config: {
     environment: "sandbox",
   },
-  searches: [
-    {
-      search_id: "people:profiles:exa@1",
-      config: {
-        limit: 1,
-        filters: {
-          query: "Find all employees of pipe0",
-        },
+  search: {
+    search_id: "people:profiles:exa@1",
+    config: {
+      limit: 1,
+      filters: {
+        query: "Find all employees of pipe0",
       },
     },
-  ],
+  },
 });
 ```
 
+## Rate limits — handled for you
+
+pipe0's API [never rejects correct clients](https://pipe0.com/docs/rate-limits): work is always
+accepted and scheduled by task priority, driven by how many records your organization has
+queued. This SDK implements that contract end to end:
+
+- **429s are absorbed automatically** — `org-rate-limited` waits out the server's
+  `Retry-After`; `queue-limit-exceeded` (the queued-record hard ceiling) backoff-retries the
+  create. Only an exhausted wait budget throws (`Pipe0RateLimitError`). Opt out with
+  `autoRetry429: false`.
+- **`pipeInBatches` paces itself** — the rolling pool submits the next batch only when the
+  capacity headers (`X-P1/P2/P3-Capacity`) say it would still be admitted at `priorityFloor`
+  (default 2) or better, so large jobs never sink themselves to the slow lane.
+- **Aborting cancels server-side** — when your `AbortSignal` fires, still-pending runs are
+  canceled remotely and their records return to your capacity instantly. Opt out with
+  `cancelOnAbort: false`.
+- **Manual control** — `pipes.cancel(runId)` / `searches.cancel(runId)`, plus `pipe0.capacity`
+  and the `onCapacity` callback for the live capacity snapshot.
+
 ## Useful links
 
 - [Documentation](https://pipe0.com/resources/documentation)

package/dist/capacity-tracker.d.mts

@@ -0,0 +1,64 @@
+//#region src/capacity-tracker.d.ts
+/**
+ * Client-side estimate of the organization's queue capacity, driven by the
+ * `X-Task-Priority` / `X-P1-Capacity` / `X-P2-Capacity` / `X-P3-Capacity`
+ * headers that pipe0's run-creating endpoints return on every response.
+ *
+ * The server never rejects below the hard ceiling — submissions just enter at
+ * a worse priority — so pacing must be capacity-led rather than error-led:
+ * the last create's headers are the authoritative baseline, records the SDK
+ * observes completing (via its own polls or cancels) are credited back, and
+ * any drift from other clients consuming capacity self-corrects at the next
+ * create response.
+ */
+/** Estimated remaining records per priority window (P1 ≤ P2 ≤ P3). */
+interface CapacitySnapshot {
+  /** Priority the most recently observed run was admitted at. */
+  taskPriority: 1 | 2 | 3;
+  /** Records that can still be submitted at priority 1. */
+  p1: number;
+  /** Records that can still be submitted at priority 2 or better. */
+  p2: number;
+  /** Records that can still be submitted at all — at 0, submissions 429. */
+  p3: number;
+  /** When the underlying headers were observed (ms epoch). */
+  observedAt: number;
+}
+declare class CapacityTracker {
+  /** Last authoritative header observation; null until the first create. */
+  private base;
+  /** Records of creates issued whose response has not settled yet. */
+  private pending;
+  /** Records credited back (completions/cancels) since `base` was observed. */
+  private credited;
+  /** runId → records, for crediting terminal runs exactly once. */
+  private runRecords;
+  /**
+   * Re-baseline from a response's headers. Returns the adjusted snapshot, or
+   * null when the response carries no capacity headers (e.g. an
+   * `org-rate-limited` 429 emitted by middleware before the handler ran).
+   */
+  observeHeaders(headers: Headers): CapacitySnapshot | null;
+  /** Call synchronously BEFORE issuing a create — prevents two concurrent submitters from double-spending the same estimate. */
+  onCreateIssued(records: number): void;
+  /** Call after the create response settled (the middleware has re-baselined by then). */
+  onCreateSettled(records: number): void;
+  /** Remember a run's record weight so its completion can be credited back. */
+  registerRun(runId: string, records: number): void;
+  /**
+   * Credit a run's records back to every window estimate. The Map delete
+   * makes double-crediting (cancel + a later poll observing "canceled")
+   * impossible. Returns the credited record count (0 if unknown/already credited).
+   */
+  creditTerminal(runId: string): number;
+  /**
+   * Estimated remaining records in the given priority window. Null when no
+   * create has been observed yet — callers treat that as "gate open".
+   */
+  estimate(floor: 1 | 2 | 3): number | null;
+  /** The current adjusted snapshot, or null before the first observation. */
+  snapshot(): CapacitySnapshot | null;
+}
+//#endregion
+export { CapacitySnapshot, CapacityTracker };
+//# sourceMappingURL=capacity-tracker.d.mts.map

package/dist/capacity-tracker.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity-tracker.d.mts","names":[],"sources":["../src/capacity-tracker.ts"],"mappings":";;AAcA;;;;;;;;;;;AAeA;AAAA,UAfiB,gBAAA;;EAEf,YAAA;EA4BkC;EA1BlC,EAAA;EAwF4B;EAtF5B,EAAA;EAWQ;EATR,EAAA;EAaQ;EAXR,UAAA;AAAA;AAAA,cAKW,eAAA;EAeI;EAAA,QAbP,IAAA;EAiCR;EAAA,QA/BQ,OAAA;EAoCR;EAAA,QAlCQ,QAAA;EAuCR;EAAA,QArCQ,UAAA;EAqCmB;;;;;EA9B3B,cAAA,CAAe,OAAA,EAAS,OAAA,GAAU,gBAAA;EA8DtB;EA1CZ,cAAA,CAAe,OAAA;EA0Ca;EArC5B,eAAA,CAAgB,OAAA;;EAKhB,WAAA,CAAY,KAAA,UAAe,OAAA;;;;;;EAa3B,cAAA,CAAe,KAAA;;;;;EAYf,QAAA,CAAS,KAAA;;EAOT,QAAA,CAAA,GAAY,gBAAA;AAAA"}

package/dist/capacity-tracker.mjs

@@ -0,0 +1,87 @@
+//#region src/capacity-tracker.ts
+const MAX_TRACKED_RUNS = 1e3;
+var CapacityTracker = class {
+	/** Last authoritative header observation; null until the first create. */
+	base = null;
+	/** Records of creates issued whose response has not settled yet. */
+	pending = 0;
+	/** Records credited back (completions/cancels) since `base` was observed. */
+	credited = 0;
+	/** runId → records, for crediting terminal runs exactly once. */
+	runRecords = /* @__PURE__ */ new Map();
+	/**
+	* Re-baseline from a response's headers. Returns the adjusted snapshot, or
+	* null when the response carries no capacity headers (e.g. an
+	* `org-rate-limited` 429 emitted by middleware before the handler ran).
+	*/
+	observeHeaders(headers) {
+		if (headers.get("X-P3-Capacity") === null) return null;
+		const num = (name) => {
+			const value = Number(headers.get(name));
+			return Number.isFinite(value) ? Math.max(0, value) : 0;
+		};
+		const priority = Number(headers.get("X-Task-Priority"));
+		this.base = {
+			taskPriority: priority === 2 || priority === 3 ? priority : 1,
+			p1: num("X-P1-Capacity"),
+			p2: num("X-P2-Capacity"),
+			p3: num("X-P3-Capacity"),
+			observedAt: Date.now()
+		};
+		this.credited = 0;
+		return this.snapshot();
+	}
+	/** Call synchronously BEFORE issuing a create — prevents two concurrent submitters from double-spending the same estimate. */
+	onCreateIssued(records) {
+		this.pending += records;
+	}
+	/** Call after the create response settled (the middleware has re-baselined by then). */
+	onCreateSettled(records) {
+		this.pending = Math.max(0, this.pending - records);
+	}
+	/** Remember a run's record weight so its completion can be credited back. */
+	registerRun(runId, records) {
+		this.runRecords.set(runId, records);
+		if (this.runRecords.size > MAX_TRACKED_RUNS) {
+			const oldest = this.runRecords.keys().next().value;
+			if (oldest !== void 0) this.runRecords.delete(oldest);
+		}
+	}
+	/**
+	* Credit a run's records back to every window estimate. The Map delete
+	* makes double-crediting (cancel + a later poll observing "canceled")
+	* impossible. Returns the credited record count (0 if unknown/already credited).
+	*/
+	creditTerminal(runId) {
+		const records = this.runRecords.get(runId);
+		if (records === void 0) return 0;
+		this.runRecords.delete(runId);
+		this.credited += records;
+		return records;
+	}
+	/**
+	* Estimated remaining records in the given priority window. Null when no
+	* create has been observed yet — callers treat that as "gate open".
+	*/
+	estimate(floor) {
+		if (this.base === null) return null;
+		const window = floor === 1 ? this.base.p1 : floor === 2 ? this.base.p2 : this.base.p3;
+		return Math.max(0, window - this.pending + this.credited);
+	}
+	/** The current adjusted snapshot, or null before the first observation. */
+	snapshot() {
+		if (this.base === null) return null;
+		const adjust = (value) => Math.max(0, value - this.pending + this.credited);
+		return {
+			taskPriority: this.base.taskPriority,
+			p1: adjust(this.base.p1),
+			p2: adjust(this.base.p2),
+			p3: adjust(this.base.p3),
+			observedAt: this.base.observedAt
+		};
+	}
+};
+
+//#endregion
+export { CapacityTracker };
+//# sourceMappingURL=capacity-tracker.mjs.map

package/dist/capacity-tracker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity-tracker.mjs","names":[],"sources":["../src/capacity-tracker.ts"],"sourcesContent":["/**\n * Client-side estimate of the organization's queue capacity, driven by the\n * `X-Task-Priority` / `X-P1-Capacity` / `X-P2-Capacity` / `X-P3-Capacity`\n * headers that pipe0's run-creating endpoints return on every response.\n *\n * The server never rejects below the hard ceiling — submissions just enter at\n * a worse priority — so pacing must be capacity-led rather than error-led:\n * the last create's headers are the authoritative baseline, records the SDK\n * observes completing (via its own polls or cancels) are credited back, and\n * any drift from other clients consuming capacity self-corrects at the next\n * create response.\n */\n\n/** Estimated remaining records per priority window (P1 ≤ P2 ≤ P3). */\nexport interface CapacitySnapshot {\n  /** Priority the most recently observed run was admitted at. */\n  taskPriority: 1 | 2 | 3;\n  /** Records that can still be submitted at priority 1. */\n  p1: number;\n  /** Records that can still be submitted at priority 2 or better. */\n  p2: number;\n  /** Records that can still be submitted at all — at 0, submissions 429. */\n  p3: number;\n  /** When the underlying headers were observed (ms epoch). */\n  observedAt: number;\n}\n\nconst MAX_TRACKED_RUNS = 1000;\n\nexport class CapacityTracker {\n  /** Last authoritative header observation; null until the first create. */\n  private base: CapacitySnapshot | null = null;\n  /** Records of creates issued whose response has not settled yet. */\n  private pending = 0;\n  /** Records credited back (completions/cancels) since `base` was observed. */\n  private credited = 0;\n  /** runId → records, for crediting terminal runs exactly once. */\n  private runRecords = new Map<string, number>();\n\n  /**\n   * Re-baseline from a response's headers. Returns the adjusted snapshot, or\n   * null when the response carries no capacity headers (e.g. an\n   * `org-rate-limited` 429 emitted by middleware before the handler ran).\n   */\n  observeHeaders(headers: Headers): CapacitySnapshot | null {\n    if (headers.get(\"X-P3-Capacity\") === null) return null;\n    const num = (name: string) => {\n      const value = Number(headers.get(name));\n      return Number.isFinite(value) ? Math.max(0, value) : 0;\n    };\n    const priority = Number(headers.get(\"X-Task-Priority\"));\n    this.base = {\n      taskPriority: priority === 2 || priority === 3 ? priority : 1,\n      p1: num(\"X-P1-Capacity\"),\n      p2: num(\"X-P2-Capacity\"),\n      p3: num(\"X-P3-Capacity\"),\n      observedAt: Date.now(),\n    };\n    // The new baseline already reflects everything the server has seen.\n    this.credited = 0;\n    return this.snapshot();\n  }\n\n  /** Call synchronously BEFORE issuing a create — prevents two concurrent submitters from double-spending the same estimate. */\n  onCreateIssued(records: number): void {\n    this.pending += records;\n  }\n\n  /** Call after the create response settled (the middleware has re-baselined by then). */\n  onCreateSettled(records: number): void {\n    this.pending = Math.max(0, this.pending - records);\n  }\n\n  /** Remember a run's record weight so its completion can be credited back. */\n  registerRun(runId: string, records: number): void {\n    this.runRecords.set(runId, records);\n    if (this.runRecords.size > MAX_TRACKED_RUNS) {\n      const oldest = this.runRecords.keys().next().value;\n      if (oldest !== undefined) this.runRecords.delete(oldest);\n    }\n  }\n\n  /**\n   * Credit a run's records back to every window estimate. The Map delete\n   * makes double-crediting (cancel + a later poll observing \"canceled\")\n   * impossible. Returns the credited record count (0 if unknown/already credited).\n   */\n  creditTerminal(runId: string): number {\n    const records = this.runRecords.get(runId);\n    if (records === undefined) return 0;\n    this.runRecords.delete(runId);\n    this.credited += records;\n    return records;\n  }\n\n  /**\n   * Estimated remaining records in the given priority window. Null when no\n   * create has been observed yet — callers treat that as \"gate open\".\n   */\n  estimate(floor: 1 | 2 | 3): number | null {\n    if (this.base === null) return null;\n    const window = floor === 1 ? this.base.p1 : floor === 2 ? this.base.p2 : this.base.p3;\n    return Math.max(0, window - this.pending + this.credited);\n  }\n\n  /** The current adjusted snapshot, or null before the first observation. */\n  snapshot(): CapacitySnapshot | null {\n    if (this.base === null) return null;\n    const adjust = (value: number) => Math.max(0, value - this.pending + this.credited);\n    return {\n      taskPriority: this.base.taskPriority,\n      p1: adjust(this.base.p1),\n      p2: adjust(this.base.p2),\n      p3: adjust(this.base.p3),\n      observedAt: this.base.observedAt,\n    };\n  }\n}\n"],"mappings":";AA2BA,MAAM,mBAAmB;AAEzB,IAAa,kBAAb,MAA6B;;CAE3B,AAAQ,OAAgC;;CAExC,AAAQ,UAAU;;CAElB,AAAQ,WAAW;;CAEnB,AAAQ,6BAAa,IAAI,KAAqB;;;;;;CAO9C,eAAe,SAA2C;AACxD,MAAI,QAAQ,IAAI,gBAAgB,KAAK,KAAM,QAAO;EAClD,MAAM,OAAO,SAAiB;GAC5B,MAAM,QAAQ,OAAO,QAAQ,IAAI,KAAK,CAAC;AACvC,UAAO,OAAO,SAAS,MAAM,GAAG,KAAK,IAAI,GAAG,MAAM,GAAG;;EAEvD,MAAM,WAAW,OAAO,QAAQ,IAAI,kBAAkB,CAAC;AACvD,OAAK,OAAO;GACV,cAAc,aAAa,KAAK,aAAa,IAAI,WAAW;GAC5D,IAAI,IAAI,gBAAgB;GACxB,IAAI,IAAI,gBAAgB;GACxB,IAAI,IAAI,gBAAgB;GACxB,YAAY,KAAK,KAAK;GACvB;AAED,OAAK,WAAW;AAChB,SAAO,KAAK,UAAU;;;CAIxB,eAAe,SAAuB;AACpC,OAAK,WAAW;;;CAIlB,gBAAgB,SAAuB;AACrC,OAAK,UAAU,KAAK,IAAI,GAAG,KAAK,UAAU,QAAQ;;;CAIpD,YAAY,OAAe,SAAuB;AAChD,OAAK,WAAW,IAAI,OAAO,QAAQ;AACnC,MAAI,KAAK,WAAW,OAAO,kBAAkB;GAC3C,MAAM,SAAS,KAAK,WAAW,MAAM,CAAC,MAAM,CAAC;AAC7C,OAAI,WAAW,OAAW,MAAK,WAAW,OAAO,OAAO;;;;;;;;CAS5D,eAAe,OAAuB;EACpC,MAAM,UAAU,KAAK,WAAW,IAAI,MAAM;AAC1C,MAAI,YAAY,OAAW,QAAO;AAClC,OAAK,WAAW,OAAO,MAAM;AAC7B,OAAK,YAAY;AACjB,SAAO;;;;;;CAOT,SAAS,OAAiC;AACxC,MAAI,KAAK,SAAS,KAAM,QAAO;EAC/B,MAAM,SAAS,UAAU,IAAI,KAAK,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,KAAK,KAAK,KAAK;AACnF,SAAO,KAAK,IAAI,GAAG,SAAS,KAAK,UAAU,KAAK,SAAS;;;CAI3D,WAAoC;AAClC,MAAI,KAAK,SAAS,KAAM,QAAO;EAC/B,MAAM,UAAU,UAAkB,KAAK,IAAI,GAAG,QAAQ,KAAK,UAAU,KAAK,SAAS;AACnF,SAAO;GACL,cAAc,KAAK,KAAK;GACxB,IAAI,OAAO,KAAK,KAAK,GAAG;GACxB,IAAI,OAAO,KAAK,KAAK,GAAG;GACxB,IAAI,OAAO,KAAK,KAAK,GAAG;GACxB,YAAY,KAAK,KAAK;GACvB"}