@productcraft/core 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -276,9 +276,18 @@ declare class Page<Item> {
     readonly has_more: boolean;
     readonly next_cursor: string | null;
     readonly lastResponse: LastResponse;
-    constructor(body: PageResponse<Item>, fetchPage: (cursor: string) => PagePromise<Item>);
+    /**
+     * @param usedCursors The cursors already sent to reach this page (this
+     *   page's own included). A `next_cursor` among them means the API is
+     *   handing back a page it already returned, and following it would loop.
+     */
+    constructor(body: PageResponse<Item>, fetchPage: (cursor: string) => PagePromise<Item>, usedCursors?: Iterable<string>);
     hasNextPage(): boolean;
-    /** Fetch the following page. Throws when there is none (check `hasNextPage()` first). */
+    /**
+     * Fetch the following page. Throws when there is none (check `hasNextPage()` first),
+     * and when the API returns a `next_cursor` this walk already sent: that would
+     * fetch the same page forever, so `for await` stops with an error instead.
+     */
     getNextPage(): PagePromise<Item>;
     /** The wire shape, so `JSON.stringify(page)` matches the API response. */
     toJSON(): PageResponse<Item>;
@@ -343,6 +352,36 @@ declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
  * const event = await verifyWebhook({ payload: rawBody, headers: req.headers, secret: process.env.WEBHOOK_SECRET! });
  */
 declare function verifyWebhook<T = unknown>(params: VerifyWebhookParams): Promise<T>;
+interface SignWebhookParams {
+    /**
+     * The event to sign: a string or bytes are signed as-is; any other value is
+     * `JSON.stringify`-ed first (the returned `payload` is that exact string).
+     */
+    payload: WebhookPayload | Record<string, unknown> | unknown[];
+    /** The endpoint's signing secret (`whsec_…`, or a plain pre-Standard-Webhooks secret). */
+    secret: string;
+    /** `webhook-id`. Default: a random `msg_…` id. */
+    id?: string;
+    /** Unix seconds for `webhook-timestamp`. Default: now. */
+    timestamp?: number;
+}
+interface SignedWebhook {
+    /** The exact body that was signed: send or verify this, byte for byte. */
+    payload: string;
+    /** `webhook-id`, `webhook-timestamp`, `webhook-signature` (and `content-type`). */
+    headers: Record<string, string>;
+}
+/**
+ * Sign a payload the way ProductCraft signs webhooks (Standard Webhooks,
+ * `v1,<base64 HMAC-SHA256>` over `<id>.<timestamp>.<body>`), for testing your
+ * handler without a live delivery. `verifyWebhook` and `webhooks.unwrap`
+ * accept the result.
+ *
+ * @example
+ * const { payload, headers } = await signWebhook({ payload: { id: "evt_1", type: "user.signup", data: {} }, secret });
+ * const event = await verifyWebhook({ payload, headers, secret });
+ */
+declare function signWebhook(params: SignWebhookParams): Promise<SignedWebhook>;
 
 /**
  * `APIClient`: the hand-written runtime every generated resource method
@@ -481,9 +520,13 @@ declare class APIClient {
         secret?: string | readonly string[];
         toleranceSeconds?: number;
     }, envVar?: string): Promise<T>;
+    /** Sign a test payload with `params.secret`, else `webhookSecret`, else `envVar` (`webhooks.sign`). */
+    signWebhook(params: Omit<SignWebhookParams, "secret"> & {
+        secret?: string;
+    }, envVar?: string): Promise<SignedWebhook>;
 }
 
 /** This package's version, injected at build time from package.json. */
 declare const CORE_VERSION: string;
 
-export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, type ClientOptions, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, type ErrorParam, type HTTPMethod, IdempotencyKeyReuseError, InternalServerError, type LastResponse, type LogLevel, type Logger, MAX_RETRY_AFTER_MS, NotFoundError, type OpenEnum, type PCAuth, type PCClientConfig, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, type PageResponse, PermissionDeniedError, type PollConfig, type PollOptions, ProductCraftError, RateLimitError, type RateLimitInfo, type RawResult, type RequestOptions, type RequestSpec, type SDKIdentity, type ToArrayOptions, UnprocessableEntityError, type VerifyWebhookParams, type WebhookHeaders, type WebhookPayload, WebhookVerificationError, type WithResponse, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, timingSafeEqual, verifyWebhook };
+export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, type ClientOptions, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, type ErrorParam, type HTTPMethod, IdempotencyKeyReuseError, InternalServerError, type LastResponse, type LogLevel, type Logger, MAX_RETRY_AFTER_MS, NotFoundError, type OpenEnum, type PCAuth, type PCClientConfig, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, type PageResponse, PermissionDeniedError, type PollConfig, type PollOptions, ProductCraftError, RateLimitError, type RateLimitInfo, type RawResult, type RequestOptions, type RequestSpec, type SDKIdentity, type SignWebhookParams, type SignedWebhook, type ToArrayOptions, UnprocessableEntityError, type VerifyWebhookParams, type WebhookHeaders, type WebhookPayload, WebhookVerificationError, type WithResponse, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, signWebhook, timingSafeEqual, verifyWebhook };

package/dist/index.d.ts

@@ -276,9 +276,18 @@ declare class Page<Item> {
     readonly has_more: boolean;
     readonly next_cursor: string | null;
     readonly lastResponse: LastResponse;
-    constructor(body: PageResponse<Item>, fetchPage: (cursor: string) => PagePromise<Item>);
+    /**
+     * @param usedCursors The cursors already sent to reach this page (this
+     *   page's own included). A `next_cursor` among them means the API is
+     *   handing back a page it already returned, and following it would loop.
+     */
+    constructor(body: PageResponse<Item>, fetchPage: (cursor: string) => PagePromise<Item>, usedCursors?: Iterable<string>);
     hasNextPage(): boolean;
-    /** Fetch the following page. Throws when there is none (check `hasNextPage()` first). */
+    /**
+     * Fetch the following page. Throws when there is none (check `hasNextPage()` first),
+     * and when the API returns a `next_cursor` this walk already sent: that would
+     * fetch the same page forever, so `for await` stops with an error instead.
+     */
     getNextPage(): PagePromise<Item>;
     /** The wire shape, so `JSON.stringify(page)` matches the API response. */
     toJSON(): PageResponse<Item>;
@@ -343,6 +352,36 @@ declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
  * const event = await verifyWebhook({ payload: rawBody, headers: req.headers, secret: process.env.WEBHOOK_SECRET! });
  */
 declare function verifyWebhook<T = unknown>(params: VerifyWebhookParams): Promise<T>;
+interface SignWebhookParams {
+    /**
+     * The event to sign: a string or bytes are signed as-is; any other value is
+     * `JSON.stringify`-ed first (the returned `payload` is that exact string).
+     */
+    payload: WebhookPayload | Record<string, unknown> | unknown[];
+    /** The endpoint's signing secret (`whsec_…`, or a plain pre-Standard-Webhooks secret). */
+    secret: string;
+    /** `webhook-id`. Default: a random `msg_…` id. */
+    id?: string;
+    /** Unix seconds for `webhook-timestamp`. Default: now. */
+    timestamp?: number;
+}
+interface SignedWebhook {
+    /** The exact body that was signed: send or verify this, byte for byte. */
+    payload: string;
+    /** `webhook-id`, `webhook-timestamp`, `webhook-signature` (and `content-type`). */
+    headers: Record<string, string>;
+}
+/**
+ * Sign a payload the way ProductCraft signs webhooks (Standard Webhooks,
+ * `v1,<base64 HMAC-SHA256>` over `<id>.<timestamp>.<body>`), for testing your
+ * handler without a live delivery. `verifyWebhook` and `webhooks.unwrap`
+ * accept the result.
+ *
+ * @example
+ * const { payload, headers } = await signWebhook({ payload: { id: "evt_1", type: "user.signup", data: {} }, secret });
+ * const event = await verifyWebhook({ payload, headers, secret });
+ */
+declare function signWebhook(params: SignWebhookParams): Promise<SignedWebhook>;
 
 /**
  * `APIClient`: the hand-written runtime every generated resource method
@@ -481,9 +520,13 @@ declare class APIClient {
         secret?: string | readonly string[];
         toleranceSeconds?: number;
     }, envVar?: string): Promise<T>;
+    /** Sign a test payload with `params.secret`, else `webhookSecret`, else `envVar` (`webhooks.sign`). */
+    signWebhook(params: Omit<SignWebhookParams, "secret"> & {
+        secret?: string;
+    }, envVar?: string): Promise<SignedWebhook>;
 }
 
 /** This package's version, injected at build time from package.json. */
 declare const CORE_VERSION: string;
 
-export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, type ClientOptions, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, type ErrorParam, type HTTPMethod, IdempotencyKeyReuseError, InternalServerError, type LastResponse, type LogLevel, type Logger, MAX_RETRY_AFTER_MS, NotFoundError, type OpenEnum, type PCAuth, type PCClientConfig, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, type PageResponse, PermissionDeniedError, type PollConfig, type PollOptions, ProductCraftError, RateLimitError, type RateLimitInfo, type RawResult, type RequestOptions, type RequestSpec, type SDKIdentity, type ToArrayOptions, UnprocessableEntityError, type VerifyWebhookParams, type WebhookHeaders, type WebhookPayload, WebhookVerificationError, type WithResponse, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, timingSafeEqual, verifyWebhook };
+export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, type ClientOptions, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, type ErrorParam, type HTTPMethod, IdempotencyKeyReuseError, InternalServerError, type LastResponse, type LogLevel, type Logger, MAX_RETRY_AFTER_MS, NotFoundError, type OpenEnum, type PCAuth, type PCClientConfig, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, type PageResponse, PermissionDeniedError, type PollConfig, type PollOptions, ProductCraftError, RateLimitError, type RateLimitInfo, type RawResult, type RequestOptions, type RequestSpec, type SDKIdentity, type SignWebhookParams, type SignedWebhook, type ToArrayOptions, UnprocessableEntityError, type VerifyWebhookParams, type WebhookHeaders, type WebhookPayload, WebhookVerificationError, type WithResponse, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, signWebhook, timingSafeEqual, verifyWebhook };

package/dist/index.js

@@ -3,7 +3,7 @@ import createClient from 'openapi-fetch';
 // src/legacy.ts
 
 // src/version.ts
-var CORE_VERSION = "1.0.1" ;
+var CORE_VERSION = "1.1.0" ;
 
 // src/legacy.ts
 var PC_BASE_URL = {
@@ -329,20 +329,37 @@ var Page = class {
   has_more;
   next_cursor;
   #fetchPage;
-  constructor(body, fetchPage) {
+  #usedCursors;
+  /**
+   * @param usedCursors The cursors already sent to reach this page (this
+   *   page's own included). A `next_cursor` among them means the API is
+   *   handing back a page it already returned, and following it would loop.
+   */
+  constructor(body, fetchPage, usedCursors = []) {
     this.data = Array.isArray(body?.data) ? body.data : [];
     this.next_cursor = body?.pagination?.next_cursor ?? null;
     this.has_more = Boolean(body?.pagination?.has_more) && this.next_cursor !== null;
     this.#fetchPage = fetchPage;
+    this.#usedCursors = new Set(usedCursors);
   }
   hasNextPage() {
     return this.has_more;
   }
-  /** Fetch the following page. Throws when there is none (check `hasNextPage()` first). */
+  /**
+   * Fetch the following page. Throws when there is none (check `hasNextPage()` first),
+   * and when the API returns a `next_cursor` this walk already sent: that would
+   * fetch the same page forever, so `for await` stops with an error instead.
+   */
   getNextPage() {
     if (!this.has_more || this.next_cursor === null) {
       throw new ProductCraftError("No next page; check hasNextPage() before calling getNextPage().");
     }
+    if (this.#usedCursors.has(this.next_cursor)) {
+      const requestId = this.lastResponse?.requestId;
+      throw new ProductCraftError(
+        "The API returned a next_cursor this list already used, so the next page would repeat an earlier one. Stopped instead of looping; this is an API bug" + (requestId ? ` (request id ${requestId}).` : ".")
+      );
+    }
     return this.#fetchPage(this.next_cursor);
   }
   /** The wire shape, so `JSON.stringify(page)` matches the API response. */
@@ -529,6 +546,34 @@ async function verifyWebhook(params) {
     throw new WebhookVerificationError("Webhook payload is not valid JSON.", { cause });
   }
 }
+async function signWebhook(params) {
+  const { secret } = params;
+  if (typeof secret !== "string" || secret === "") throw new WebhookVerificationError("No webhook secret was given.");
+  const raw = params.payload;
+  const payload = typeof raw === "string" ? raw : raw instanceof Uint8Array || raw instanceof ArrayBuffer ? decoder.decode(raw) : JSON.stringify(raw);
+  const id = params.id ?? `msg_${randomHex(16)}`;
+  const timestamp = Math.floor(params.timestamp ?? Date.now() / 1e3);
+  const mac = await hmacSha256(standardKey(secret), encoder.encode(`${id}.${timestamp}.${payload}`));
+  return {
+    payload,
+    headers: {
+      "content-type": "application/json",
+      "webhook-id": id,
+      "webhook-timestamp": String(timestamp),
+      "webhook-signature": `v1,${bytesToBase64(mac)}`
+    }
+  };
+}
+function bytesToBase64(bytes) {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+function randomHex(bytes) {
+  const buf = new Uint8Array(bytes);
+  globalThis.crypto.getRandomValues(buf);
+  return [...buf].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 
 // src/client.ts
 var DEFAULT_TIMEOUT_MS = 6e4;
@@ -643,15 +688,16 @@ var APIClient = class {
   }
   /** A paginated list call. `await` for one page, `for await` for every item. */
   list(spec, options = {}) {
-    const at = (cursor) => {
+    const at = (cursor, used) => {
       const pageSpec = cursor === void 0 ? spec : { ...spec, query: { ...spec.query, cursor } };
       return new PagePromise(this.#send(pageSpec, options), async (raw) => {
         const body = await this.#parseBody(pageSpec, raw);
-        const page = new Page(body, (next) => at(next));
+        const page = new Page(body, (next) => at(next, [...used, next]), used);
         return attachLastResponse(page, this.#meta(raw));
       });
     };
-    return at();
+    const first = spec.query?.cursor;
+    return at(void 0, typeof first === "string" && first !== "" ? [first] : []);
   }
   /** Retrieve repeatedly until `config.field` reaches a terminal value. */
   async poll(spec, config, options = {}) {
@@ -692,6 +738,17 @@ var APIClient = class {
     }
     return verifyWebhook({ ...params, secret });
   }
+  /** Sign a test payload with `params.secret`, else `webhookSecret`, else `envVar` (`webhooks.sign`). */
+  async signWebhook(params, envVar) {
+    const fallback = Array.isArray(this.webhookSecret) ? this.webhookSecret[0] : this.webhookSecret;
+    const secret = params.secret ?? fallback ?? (envVar ? readEnv(envVar) : void 0);
+    if (!secret) {
+      throw new ConfigurationError(
+        `No webhook secret: pass { secret }, set webhookSecret on the client${envVar ? ` or ${envVar}` : ""}.`
+      );
+    }
+    return signWebhook({ ...params, secret });
+  }
   #meta(raw) {
     return { requestId: raw.requestId, status: raw.response.status, headers: raw.response.headers };
   }
@@ -852,6 +909,6 @@ var APIClient = class {
   }
 };
 
-export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, IdempotencyKeyReuseError, InternalServerError, MAX_RETRY_AFTER_MS, NotFoundError, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, PermissionDeniedError, ProductCraftError, RateLimitError, UnprocessableEntityError, WebhookVerificationError, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, timingSafeEqual, verifyWebhook };
+export { APIClient, APIConnectionError, APIError, APIPromise, APITimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, CORE_VERSION, ConfigurationError, ConflictError, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ERROR_DOCS_URL, IdempotencyKeyReuseError, InternalServerError, MAX_RETRY_AFTER_MS, NotFoundError, PC_API_KEY_ENV, PC_AUTH_APP_ENV, PC_BASE_URL, PC_LOG_ENV, PC_WORKSPACE_ID_ENV, Page, PagePromise, PermissionDeniedError, ProductCraftError, RateLimitError, UnprocessableEntityError, WebhookVerificationError, _resetWorkspaceCache, attachLastResponse, authMiddleware, backoffMs, createOpenAPIClient, makeClient, normalizeHeaders, parseRateLimit, parseRetryAfterMs, readEnv, resolveAuth, signWebhook, timingSafeEqual, verifyWebhook };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map