@paymos/sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,464 @@
+// src/index.ts
+import { randomUUID } from "crypto";
+
+// src/errors.ts
+var PaymosError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+};
+var ConfigurationError = class extends PaymosError {
+};
+var SignatureMismatchError = class extends PaymosError {
+};
+var TimestampSkewError = class extends PaymosError {
+};
+var ApiError = class extends PaymosError {
+  status;
+  body;
+  headers;
+  problem;
+  constructor(status, body, headers) {
+    const problem = parseProblem(body);
+    const detail = problem?.detail ?? problem?.errors?.[0]?.message ?? problem?.code ?? problem?.title;
+    super(`Paymos API ${status}: ${detail || body || "empty response"}`);
+    this.status = status;
+    this.body = body;
+    this.headers = headers;
+    this.problem = problem;
+  }
+  get code() {
+    return this.problem?.errors?.[0]?.code ?? this.problem?.code ?? "";
+  }
+  get field() {
+    return this.problem?.errors?.[0]?.field ?? this.problem?.field ?? null;
+  }
+  get errors() {
+    return this.problem?.errors ?? [];
+  }
+  get retryAfterSeconds() {
+    const value = this.headers.get("retry-after");
+    if (!value) return null;
+    if (/^\d+$/.test(value)) return Number(value);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? null : Math.max(0, Math.ceil((date - Date.now()) / 1e3));
+  }
+};
+var ValidationError = class extends ApiError {
+};
+var AuthenticationError = class extends ApiError {
+};
+var NotFoundError = class extends ApiError {
+};
+var ConflictError = class extends ApiError {
+};
+var GoneError = class extends ApiError {
+};
+var RateLimitError = class extends ApiError {
+};
+var ServerError = class extends ApiError {
+};
+var UnavailableError = class extends ServerError {
+};
+function apiErrorFromResponse(status, body, headers) {
+  if (status === 400) return new ValidationError(status, body, headers);
+  if (status === 401 || status === 403) return new AuthenticationError(status, body, headers);
+  if (status === 404) return new NotFoundError(status, body, headers);
+  if (status === 409) return new ConflictError(status, body, headers);
+  if (status === 410) return new GoneError(status, body, headers);
+  if (status === 429) return new RateLimitError(status, body, headers);
+  if (status === 503) return new UnavailableError(status, body, headers);
+  if (status >= 500) return new ServerError(status, body, headers);
+  return new ApiError(status, body, headers);
+}
+function parseProblem(body) {
+  if (!body) return null;
+  try {
+    const parsed = JSON.parse(body);
+    return parsed !== null && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/signing.ts
+import { createHash, createHmac } from "crypto";
+function stringToSign(timestamp, method, path, query = "", body = "") {
+  const bodyHash = body === "" ? "" : createHash("sha256").update(body, "utf8").digest("hex");
+  return `${timestamp}
+${method.toUpperCase()}
+${path}
+${query}
+${bodyHash}`;
+}
+function sign(secret, value) {
+  return createHmac("sha256", secret).update(value, "utf8").digest("base64");
+}
+function authorizationHeader(apiKey, apiSecret, timestamp, method, path, query = "", body = "") {
+  const signature = sign(apiSecret, stringToSign(timestamp, method, path, query, body));
+  return `HMAC-SHA256 ${apiKey}:${signature}`;
+}
+function encodePathSegment(value) {
+  return rfc3986(value);
+}
+function buildQuery(filters) {
+  const valuesByKey = filters;
+  const parts = [];
+  for (const key of Object.keys(filters).sort()) {
+    const raw = valuesByKey[key];
+    if (raw === void 0 || raw === null) continue;
+    const values = Array.isArray(raw) ? [...raw].sort() : [raw];
+    if (values.length === 0) throw new TypeError(`Paymos list filter cannot be empty: ${key}`);
+    for (const value of values) {
+      if (typeof value !== "string" && typeof value !== "number" || String(value) === "") {
+        throw new TypeError(`Invalid Paymos list filter: ${key}`);
+      }
+      parts.push(`${rfc3986(key)}=${rfc3986(String(value))}`);
+    }
+  }
+  return parts.length === 0 ? "" : `?${parts.join("&")}`;
+}
+function rfc3986(value) {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+
+// src/version.ts
+var SDK_VERSION = "1.0.0";
+
+// src/http.ts
+var HttpClient = class {
+  options;
+  constructor(options) {
+    this.options = normalizeOptions(options);
+  }
+  async request(method, path, payload, query = "") {
+    const body = payload === void 0 ? "" : JSON.stringify(payload);
+    const url = `${this.options.baseUrl}${path}${query}`;
+    let attempt = 0;
+    while (true) {
+      const timestamp = Math.floor(this.options.clock() / 1e3).toString();
+      const headers = new Headers({
+        Authorization: authorizationHeader(
+          this.options.apiKey,
+          this.options.apiSecret,
+          timestamp,
+          method,
+          path,
+          query,
+          body
+        ),
+        "X-Request-Timestamp": timestamp,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": `paymos-typescript/${SDK_VERSION}`
+      });
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
+      let response;
+      try {
+        const requestInit = {
+          method,
+          headers,
+          signal: controller.signal
+        };
+        if (body !== "") requestInit.body = body;
+        response = await this.options.fetch(url, requestInit);
+      } catch (error) {
+        if (attempt >= this.options.maxRetries || !isIdempotent(method)) {
+          throw new PaymosError(`Paymos request failed: ${errorMessage(error)}`, { cause: error });
+        }
+        await sleep(backoff(this.options.baseDelayMs, ++attempt));
+        continue;
+      } finally {
+        clearTimeout(timeout);
+      }
+      if (shouldRetry(method, response.status) && attempt < this.options.maxRetries) {
+        const retryAfter = retryAfterMs(response.headers.get("retry-after"));
+        await sleep(Math.max(backoff(this.options.baseDelayMs, ++attempt), retryAfter ?? 0));
+        continue;
+      }
+      const responseBody = await response.text();
+      if (!response.ok) throw apiErrorFromResponse(response.status, responseBody, response.headers);
+      if (responseBody === "") return {};
+      try {
+        return JSON.parse(responseBody);
+      } catch (error) {
+        throw new PaymosError("Paymos API returned invalid JSON.", { cause: error });
+      }
+    }
+  }
+};
+function normalizeOptions(options) {
+  if (!options || typeof options !== "object") throw new ConfigurationError("Client options are required.");
+  const apiKey = requireString(options.apiKey, "apiKey");
+  const apiSecret = requireString(options.apiSecret, "apiSecret");
+  const baseUrl = requireString(options.baseUrl ?? "https://api.paymos.io", "baseUrl").replace(/\/$/, "");
+  const timeoutMs = options.timeoutMs ?? 3e4;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new ConfigurationError("timeoutMs must be a positive integer.");
+  }
+  const maxRetries = options.retry === false ? 0 : options.retry?.maxRetries ?? 2;
+  const baseDelayMs = options.retry === false ? 0 : options.retry?.baseDelayMs ?? 150;
+  if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) {
+    throw new ConfigurationError("retry.maxRetries must be a non-negative integer.");
+  }
+  if (!Number.isSafeInteger(baseDelayMs) || baseDelayMs < 0) {
+    throw new ConfigurationError("retry.baseDelayMs must be a non-negative integer.");
+  }
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") throw new ConfigurationError("A Fetch implementation is required.");
+  return {
+    apiKey,
+    apiSecret,
+    baseUrl,
+    timeoutMs,
+    maxRetries,
+    baseDelayMs,
+    fetch: fetchImplementation,
+    clock: options.clock ?? Date.now
+  };
+}
+function requireString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ConfigurationError(`${name} must be a non-empty string.`);
+  }
+  return value;
+}
+function isIdempotent(method) {
+  return ["GET", "HEAD", "OPTIONS"].includes(method.toUpperCase());
+}
+function shouldRetry(method, status) {
+  return status === 429 || status >= 500 && isIdempotent(method);
+}
+function backoff(baseDelayMs, attempt) {
+  return baseDelayMs * 2 ** Math.max(0, attempt - 1);
+}
+function retryAfterMs(value) {
+  if (!value) return null;
+  if (/^\d+$/.test(value)) return Number(value) * 1e3;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+function sleep(ms) {
+  return ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms));
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/resources.ts
+var InvoicesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  create(params) {
+    return this.http.request("POST", "/v1/invoices", params);
+  }
+  get(invoiceId) {
+    return this.http.request("GET", `/v1/invoices/${encodePathSegment(invoiceId)}`);
+  }
+  list(params = {}) {
+    return this.http.request("GET", "/v1/invoices", void 0, buildQuery(params));
+  }
+  async *iterate(params = {}, maxPages = 100) {
+    assertMaxPages(maxPages);
+    let cursor = params.cursor;
+    for (let pageNumber = 0; pageNumber < maxPages; pageNumber += 1) {
+      const page = await this.list(cursor === void 0 ? params : { ...params, cursor });
+      yield* page.items;
+      const next = page.next_cursor || void 0;
+      if (next === void 0) return;
+      if (next === cursor) throw new Error("Paymos API returned the same pagination cursor twice.");
+      cursor = next;
+    }
+  }
+  cancel(invoiceId, reason) {
+    assertReason(reason);
+    return this.http.request("POST", `/v1/invoices/${encodePathSegment(invoiceId)}/cancel`, { reason });
+  }
+  confirmPayment(invoiceId, params) {
+    return this.http.request("POST", `/v1/invoices/${encodePathSegment(invoiceId)}/confirm-payment`, params);
+  }
+  simulatePayment(invoiceId, stage) {
+    return this.http.request("POST", `/v1/sandbox/invoices/${encodePathSegment(invoiceId)}/simulate-payment`, {
+      stage
+    });
+  }
+};
+var WithdrawalsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  create(params) {
+    return this.http.request("POST", "/v1/withdrawals", params);
+  }
+  get(withdrawalId) {
+    return this.http.request("GET", `/v1/withdrawals/${encodePathSegment(withdrawalId)}`);
+  }
+  list(params = {}) {
+    return this.http.request("GET", "/v1/withdrawals", void 0, buildQuery(params));
+  }
+  async *iterate(params = {}, maxPages = 100) {
+    assertMaxPages(maxPages);
+    let cursor = params.cursor;
+    for (let pageNumber = 0; pageNumber < maxPages; pageNumber += 1) {
+      const page = await this.list(cursor === void 0 ? params : { ...params, cursor });
+      yield* page.items;
+      const next = page.next_cursor || void 0;
+      if (next === void 0) return;
+      if (next === cursor) throw new Error("Paymos API returned the same pagination cursor twice.");
+      cursor = next;
+    }
+  }
+  cancel(withdrawalId, reason) {
+    assertReason(reason);
+    return this.http.request("POST", `/v1/withdrawals/${encodePathSegment(withdrawalId)}/cancel`, { reason });
+  }
+  simulateCompletion(withdrawalId) {
+    return this.http.request(
+      "POST",
+      `/v1/sandbox/withdrawals/${encodePathSegment(withdrawalId)}/simulate-completion`
+    );
+  }
+};
+var BalancesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  get() {
+    return this.http.request("GET", "/v1/balances");
+  }
+};
+var SystemResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  time() {
+    return this.http.request("GET", "/v1/time");
+  }
+};
+function assertReason(reason) {
+  if (typeof reason !== "string" || reason.trim() === "" || reason.length > 500) {
+    throw new TypeError("Cancellation reason must contain 1 to 500 characters.");
+  }
+}
+function assertMaxPages(maxPages) {
+  if (!Number.isSafeInteger(maxPages) || maxPages < 1) {
+    throw new TypeError("maxPages must be a positive integer.");
+  }
+}
+
+// src/webhooks.ts
+import { createHmac as createHmac2, timingSafeEqual } from "crypto";
+var WebhookVerifier = class {
+  constructor(secret, toleranceSeconds = 300) {
+    this.secret = secret;
+    this.toleranceSeconds = toleranceSeconds;
+    if (typeof secret !== "string" || secret.trim() === "") {
+      throw new TypeError("Webhook secret must be a non-empty string.");
+    }
+    if (!Number.isSafeInteger(toleranceSeconds) || toleranceSeconds < 0) {
+      throw new TypeError("Webhook tolerance must be a non-negative integer.");
+    }
+  }
+  secret;
+  toleranceSeconds;
+  verify(signatureHeader, rawBody, now = Math.floor(Date.now() / 1e3)) {
+    try {
+      this.assertValid(signatureHeader, rawBody, now);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  assertValid(signatureHeader, rawBody, now = Math.floor(Date.now() / 1e3)) {
+    const parsed = parseHeader(signatureHeader);
+    if (!parsed) throw new SignatureMismatchError("Webhook signature header is missing or malformed.");
+    if (Math.abs(now - parsed.timestamp) > this.toleranceSeconds) {
+      throw new TimestampSkewError("Webhook timestamp is outside the allowed tolerance.");
+    }
+    const expected = createHmac2("sha256", this.secret).update(`${parsed.timestamp}.`).update(rawBody).digest();
+    const matched = parsed.signatures.some((signature) => {
+      if (!/^[0-9a-fA-F]{64}$/.test(signature)) return false;
+      const candidate = Buffer.from(signature, "hex");
+      return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+    });
+    if (!matched) throw new SignatureMismatchError("Webhook signature does not match payload.");
+  }
+  constructEvent(signatureHeader, rawBody, now = Math.floor(Date.now() / 1e3)) {
+    this.assertValid(signatureHeader, rawBody, now);
+    try {
+      return JSON.parse(rawBody.toString());
+    } catch (error) {
+      throw new TypeError("Webhook payload is not valid JSON.", { cause: error });
+    }
+  }
+};
+function parseHeader(header) {
+  if (typeof header !== "string") return null;
+  let timestamp;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const separator = part.indexOf("=");
+    if (separator < 1) continue;
+    const key = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
+    if (key === "v1" && value !== "") signatures.push(value);
+  }
+  return timestamp === void 0 || signatures.length === 0 ? null : { timestamp, signatures };
+}
+
+// src/index.ts
+var Paymos = class {
+  invoices;
+  withdrawals;
+  balances;
+  system;
+  constructor(options) {
+    const http = new HttpClient(options);
+    this.invoices = new InvoicesResource(http);
+    this.withdrawals = new WithdrawalsResource(http);
+    this.balances = new BalancesResource(http);
+    this.system = new SystemResource(http);
+  }
+};
+function externalOrderId(prefix = "order") {
+  if (!/^[A-Za-z0-9_-]{1,32}$/.test(prefix)) {
+    throw new TypeError("externalOrderId prefix must contain 1 to 32 letters, digits, underscores, or hyphens.");
+  }
+  return `${prefix}_${randomUUID()}`;
+}
+export {
+  ApiError,
+  AuthenticationError,
+  ConfigurationError,
+  ConflictError,
+  GoneError,
+  NotFoundError,
+  Paymos,
+  PaymosError,
+  RateLimitError,
+  SDK_VERSION,
+  ServerError,
+  SignatureMismatchError,
+  TimestampSkewError,
+  UnavailableError,
+  ValidationError,
+  WebhookVerifier,
+  apiErrorFromResponse,
+  authorizationHeader,
+  buildQuery,
+  encodePathSegment,
+  externalOrderId,
+  sign,
+  stringToSign
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@paymos/sdk",
+  "version": "1.0.0",
+  "description": "Official TypeScript and JavaScript SDK for the Paymos Merchant API",
+  "keywords": [
+    "paymos",
+    "payments",
+    "stablecoins",
+    "usdt",
+    "usdc",
+    "crypto",
+    "sdk"
+  ],
+  "homepage": "https://paymos.io/docs/quick-start",
+  "bugs": "https://github.com/Paymos-labs/typescript-sdk/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Paymos-labs/typescript-sdk.git"
+  },
+  "license": "MIT",
+  "author": "Paymos Labs <support@paymos.io>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepack": "npm run check && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "overrides": {
+    "esbuild": "0.28.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}