@relume_io/partner-node 2.0.1 → 2.2.0

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
 
 type CallType = 'user.get' | 'credits.get' | 'credits.charge' | 'credits.reverse';
+/** A key's environment, and the `environment` every signed call carries. */
+type Environment = 'test' | 'live';
 /** Passed to every callback, for your logs. */
 interface CallContext {
     type: CallType;
+    /**
+     * Always your secret key's: a call for the other environment is refused
+     * before any callback runs.
+     */
+    environment: Environment;
     /** Relume-Request-Id: unique per attempt. Quote it to Relume support. */
     requestId: string | null;
 }
@@ -39,7 +46,13 @@ interface Charge {
     action: string;
     siteId?: string;
     pageId?: string;
-    /** For the user's wallet statement. At most 200 characters. */
+    /**
+     * The pages one charge pays for, when it covers several (a `page.unlock`
+     * for each, with both prices multiplied by their count). Sent instead of
+     * `pageId`. Debit `partnerCredits` as for any charge.
+     */
+    pageIds?: string[];
+    /** For the user's wallet statement, e.g. `Build 3 pages`. At most 200 characters. */
     description: string;
 }
 interface ChargeResult {
@@ -245,6 +258,20 @@ interface Price {
     partnerCredits: number | null;
     relumeCredits: number;
 }
+/** What you call your credits: the word the builder shows beside amounts. */
+interface CreditUnit {
+    /** e.g. `coin`. */
+    singular: string;
+    /** e.g. `coins`. */
+    plural: string;
+    /** The https icon the builder shows beside amounts; absent when not set. */
+    iconUrl?: string;
+}
+interface PriceList {
+    data: Price[];
+    /** What the builder calls your credits, as Relume staff set it for you. */
+    creditUnit: CreditUnit;
+}
 
 declare const DEFAULT_API_BASE_URL = "https://apis.relume.io/nova/partner/v1";
 /**
@@ -356,6 +383,8 @@ interface PartnerApi {
     prices: {
         /** GET /prices: every billable action's price in this environment. */
         list(): Promise<Price[]>;
+        /** GET /prices: the prices, and what the builder calls your credits. */
+        get(): Promise<PriceList>;
     };
 }
 
@@ -451,8 +480,9 @@ declare class Relume<TRequest extends SessionRequest = SessionRequest> {
     express(): NodeHandler;
     /**
      * `POST /relume/calls`, framework-agnostic: verifies the signature and the
-     * 5-minute window, routes by `type`, runs your callback and validates what
-     * it returns. Pass the raw body exactly as received.
+     * 5-minute window, refuses a call for another environment than the secret
+     * key's (`400 environment_mismatch`), routes by `type`, runs your callback
+     * and validates what it returns. Pass the raw body exactly as received.
      */
     handleCall(input: {
         rawBody: string | Uint8Array;
@@ -522,4 +552,4 @@ declare function verifySignature(input: {
     nowSeconds?: number;
 }): Promise<VerifySignatureResult>;
 
-export { type CallContext, type CallType, type Charge, type ChargeCreditsCallback, type ChargeResult, type CreateSessionBody, type CreateSiteBody, type CreatedSite, type Credits, DEFAULT_API_BASE_URL, EMBED_HEADER, EMBED_HEADER_VALUE, type Export, type ExportStatus, type GetCreditsCallback, type GetUserCallback, type GetUserIdFromRequest, type HandlerErrorInfo, InvalidCallbackResultError, type LedgerEntry, type LedgerEntryDetail, type LedgerEntryStatus, type LedgerEntryType, MAX_SIGNATURES, type NodeHandler, type NodeRequest, type Page, type PageQuery, PagedList, type ParsedSignatureHeader, type PartnerApi, type PartnerApiErrorCode, type PartnerResponse, type Price, REQUEST_ID_HEADER, Relume, RelumeError, type RelumeErrorCode, type RelumeOptions, type RelumeResponse, type Reversal, type ReversalReason, type ReversalResult, type ReverseChargeCallback, SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, type Session, type SessionRequest, type SignatureFailure, type Site, type UsageGroup, type UsageParams, type UsageRow, type UsageTotals, type User, type UserProfile, type UserStatus, type VerifySignatureResult, computeSignature, parseSignatureHeader, signCall, verifySignature };
+export { type CallContext, type CallType, type Charge, type ChargeCreditsCallback, type ChargeResult, type CreateSessionBody, type CreateSiteBody, type CreatedSite, type CreditUnit, type Credits, DEFAULT_API_BASE_URL, EMBED_HEADER, EMBED_HEADER_VALUE, type Environment, type Export, type ExportStatus, type GetCreditsCallback, type GetUserCallback, type GetUserIdFromRequest, type HandlerErrorInfo, InvalidCallbackResultError, type LedgerEntry, type LedgerEntryDetail, type LedgerEntryStatus, type LedgerEntryType, MAX_SIGNATURES, type NodeHandler, type NodeRequest, type Page, type PageQuery, PagedList, type ParsedSignatureHeader, type PartnerApi, type PartnerApiErrorCode, type PartnerResponse, type Price, type PriceList, REQUEST_ID_HEADER, Relume, RelumeError, type RelumeErrorCode, type RelumeOptions, type RelumeResponse, type Reversal, type ReversalReason, type ReversalResult, type ReverseChargeCallback, SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, type Session, type SessionRequest, type SignatureFailure, type Site, type UsageGroup, type UsageParams, type UsageRow, type UsageTotals, type User, type UserProfile, type UserStatus, type VerifySignatureResult, computeSignature, parseSignatureHeader, signCall, verifySignature };

package/dist/index.js

@@ -1,22 +1,24 @@
 import {
   EMBED_HEADER,
   EMBED_HEADER_VALUE,
+  InvalidCallbackResultError,
   MAX_BODY_BYTES,
   MAX_SIGNATURES,
   REQUEST_ID_HEADER,
   SIGNATURE_HEADER,
   SIGNATURE_TOLERANCE_SECONDS,
-  absent,
+  checkChargeResult,
+  checkCredits,
+  checkReversalResult,
+  checkUserProfile,
   computeSignature,
   errorResponse,
-  isEmail,
-  isHttpsUrl,
   isRecord,
-  isString,
-  isWhole,
   jsonResponse,
+  keyEnvironment,
   methodNotAllowed,
   mountedRouteOf,
+  parseCall,
   parseSignatureHeader,
   payloadTooLarge,
   preflight,
@@ -24,7 +26,7 @@ import {
   routeOf,
   signCall,
   verifySignature
-} from "./chunk-HPVVBUR7.js";
+} from "./chunk-WUW4CIBP.js";
 
 // src/adapters/express.ts
 var PayloadTooLargeError = class extends Error {
@@ -226,7 +228,7 @@ function fetchHandler(client, maxBodyBytes) {
 
 // src/api.ts
 var DEFAULT_API_BASE_URL = "https://apis.relume.io/nova/partner/v1";
-var SDK_VERSION = "2.0.1";
+var SDK_VERSION = "2.2.0";
 var USER_AGENT = `relume-partner-node/${SDK_VERSION}`;
 var DEFAULT_API_TIMEOUT_MS = 15e3;
 var DEFAULT_MAX_RETRIES = 2;
@@ -377,171 +379,6 @@ function isSession(value) {
   return isRecord(value) && typeof value.clientSecret === "string" && typeof value.expiresAt === "string";
 }
 
-// src/calls.ts
-var CALL_TYPES = [
-  "user.get",
-  "credits.get",
-  "credits.charge",
-  "credits.reverse"
-];
-var InvalidCallbackResultError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidCallbackResultError";
-  }
-};
-function optionalString(value, max) {
-  if (value === void 0 || value === null) {
-    return { ok: true, value: void 0 };
-  }
-  return isString(value, 1, max) ? { ok: true, value } : { ok: false };
-}
-function isCallType(value) {
-  return CALL_TYPES.some((type) => type === value);
-}
-function parseCall(body) {
-  if (!isRecord(body)) {
-    return {
-      ok: false,
-      code: "invalid_request",
-      message: "The body must be a JSON object."
-    };
-  }
-  const { type } = body;
-  if (!isCallType(type)) {
-    return {
-      ok: false,
-      code: "unsupported_call_type",
-      message: `Unsupported call type: ${JSON.stringify(type ?? null).slice(0, 64)}.`
-    };
-  }
-  const invalid = (field) => ({
-    ok: false,
-    code: "invalid_request",
-    message: `Invalid ${field} for ${type}.`,
-    type
-  });
-  const { userId } = body;
-  if (!isString(userId, 1, 128)) return invalid("userId");
-  switch (type) {
-    case "user.get":
-    case "credits.get":
-      return { ok: true, call: { type, userId } };
-    case "credits.charge": {
-      const { chargeId, partnerCredits, relumeCredits, action, description } = body;
-      if (!isString(chargeId, 1, 64)) return invalid("chargeId");
-      if (!isWhole(partnerCredits, 1)) return invalid("partnerCredits");
-      if (!isWhole(relumeCredits, 0)) return invalid("relumeCredits");
-      if (!isString(action, 1, 200)) return invalid("action");
-      if (!isString(description, 0, 200)) return invalid("description");
-      const siteId = optionalString(body.siteId, 200);
-      if (!siteId.ok) return invalid("siteId");
-      const pageId = optionalString(body.pageId, 200);
-      if (!pageId.ok) return invalid("pageId");
-      const charge = {
-        userId,
-        chargeId,
-        partnerCredits,
-        relumeCredits,
-        action,
-        description
-      };
-      if (siteId.value !== void 0) charge.siteId = siteId.value;
-      if (pageId.value !== void 0) charge.pageId = pageId.value;
-      return { ok: true, call: { type, charge } };
-    }
-    case "credits.reverse": {
-      const { reversalId, partnerCredits, relumeCredits, reason } = body;
-      if (!isString(reversalId, 1, 64)) return invalid("reversalId");
-      if (!isWhole(partnerCredits, 1)) return invalid("partnerCredits");
-      if (!isWhole(relumeCredits, 0)) return invalid("relumeCredits");
-      if (!isString(reason, 1, 200)) return invalid("reason");
-      const chargeId = optionalString(body.chargeId, 64);
-      if (!chargeId.ok) return invalid("chargeId");
-      const reversal = {
-        userId,
-        reversalId,
-        partnerCredits,
-        relumeCredits,
-        reason
-      };
-      if (chargeId.value !== void 0) reversal.chargeId = chargeId.value;
-      return { ok: true, call: { type, reversal } };
-    }
-  }
-}
-function balanceOrThrow(value, callback) {
-  if (!isWhole(value, 0)) {
-    throw new InvalidCallbackResultError(
-      `${callback} must return a balance that is a whole number, zero or more; got ${JSON.stringify(value)}.`
-    );
-  }
-  return value;
-}
-function checkUserProfile(value) {
-  if (value === null || value === void 0) return null;
-  if (!isRecord(value)) {
-    throw new InvalidCallbackResultError(
-      "onGetUser must return { name?, email?, avatarUrl? } or null."
-    );
-  }
-  const profile = {};
-  const { name, email, avatarUrl } = value;
-  if (!absent(name)) {
-    if (!isString(name, 1, 200)) {
-      throw new InvalidCallbackResultError(
-        "onGetUser: name must be a string of at most 200 characters."
-      );
-    }
-    profile.name = name;
-  }
-  if (!absent(email)) {
-    if (!isEmail(email)) {
-      throw new InvalidCallbackResultError(
-        "onGetUser: email must be a valid email address."
-      );
-    }
-    profile.email = email;
-  }
-  if (!absent(avatarUrl)) {
-    if (!isHttpsUrl(avatarUrl)) {
-      throw new InvalidCallbackResultError(
-        "onGetUser: avatarUrl must be an https URL."
-      );
-    }
-    profile.avatarUrl = avatarUrl;
-  }
-  return profile;
-}
-function checkCredits(value) {
-  if (!isRecord(value)) {
-    throw new InvalidCallbackResultError(
-      "onGetCredits must return { balance }."
-    );
-  }
-  return { balance: balanceOrThrow(value.balance, "onGetCredits") };
-}
-function optionalBalance(value, callback) {
-  return absent(value.balance) ? {} : { balance: balanceOrThrow(value.balance, callback) };
-}
-function checkChargeResult(value) {
-  if (!isRecord(value) || typeof value.ok !== "boolean") {
-    throw new InvalidCallbackResultError(
-      "onChargeCredits must return { ok: boolean, balance? }."
-    );
-  }
-  return { ok: value.ok, ...optionalBalance(value, "onChargeCredits") };
-}
-function checkReversalResult(value) {
-  if (value === void 0 || value === null) return {};
-  if (!isRecord(value)) {
-    throw new InvalidCallbackResultError(
-      "onReverseCharge must return { balance? } or nothing."
-    );
-  }
-  return optionalBalance(value, "onReverseCharge");
-}
-
 // src/pages.ts
 function isPage(value) {
   return isRecord(value) && Array.isArray(value.data) && typeof value.nextCursor === "string" && typeof value.hasMore === "boolean";
@@ -606,8 +443,9 @@ var isLedgerEntryDetail = hasStrings(
   "type",
   "status"
 );
+var isCreditUnit = hasStrings("singular", "plural");
 function isPriceList(value) {
-  return isRecord(value) && Array.isArray(value.data);
+  return isRecord(value) && Array.isArray(value.data) && isCreditUnit(value.creditUnit);
 }
 function segment(name, value) {
   if (typeof value !== "string" || value === "") {
@@ -686,7 +524,8 @@ function partnerApi(config) {
       })
     },
     prices: {
-      list: async () => (await get("/prices", isPriceList)).data
+      list: async () => (await get("/prices", isPriceList)).data,
+      get: () => get("/prices", isPriceList)
     }
   };
 }
@@ -723,6 +562,7 @@ var Relume = class _Relume {
    */
   fetchHandler;
   #secretKey;
+  #environment;
   #api;
   #callbacks = {};
   #onHandlerError;
@@ -742,6 +582,12 @@ var Relume = class _Relume {
         "Relume.init: that is a publishable key. Pass the secret key (sk_\u2026); the publishable key goes to the embed."
       );
     }
+    const environment = keyEnvironment(secretKey);
+    if (environment === null) {
+      throw new TypeError(
+        "Relume.init: secretKey must start with sk_test_ or sk_live_."
+      );
+    }
     const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) {
       throw new TypeError(
@@ -749,6 +595,7 @@ var Relume = class _Relume {
       );
     }
     this.#secretKey = secretKey;
+    this.#environment = environment;
     this.#now = options.now ?? Date.now;
     this.#api = {
       secretKey,
@@ -824,8 +671,9 @@ var Relume = class _Relume {
   }
   /**
    * `POST /relume/calls`, framework-agnostic: verifies the signature and the
-   * 5-minute window, routes by `type`, runs your callback and validates what
-   * it returns. Pass the raw body exactly as received.
+   * 5-minute window, refuses a call for another environment than the secret
+   * key's (`400 environment_mismatch`), routes by `type`, runs your callback
+   * and validates what it returns. Pass the raw body exactly as received.
    */
   async handleCall(input) {
     const requestId = input.requestId ?? null;
@@ -849,10 +697,14 @@ var Relume = class _Relume {
         "The body is not valid JSON."
       );
     }
-    const parsed = parseCall(body);
+    const parsed = parseCall(body, this.#environment);
     if (!parsed.ok) return errorResponse(400, parsed.code, parsed.message);
     const { call } = parsed;
-    const context = { type: call.type, requestId };
+    const context = {
+      type: call.type,
+      environment: this.#environment,
+      requestId
+    };
     const callbackName = CALLBACK_FOR[call.type];
     if (!this.#callbacks[callbackName]) {
       this.#onHandlerError(