@paymos/sdk 1.0.0 → 2.0.3

package/CHANGELOG.md

@@ -1,9 +1,30 @@
-# Changelog
-
-## 1.0.0
-
-- Initial official TypeScript and JavaScript SDK.
-- Invoice create, get, list, iterate, cancel, confirm, and sandbox simulation.
-- Withdrawal create, get, list, iterate, cancel, and sandbox simulation.
-- Balance retrieval.
-- HMAC-SHA256 request signing, typed RFC 9457 errors, bounded retries, and webhook verification.
+# Changelog
+
+## [2.0.3] - 2026-07-19
+
+- fix: align SDK problem details semantics
+
+## [2.0.2] - 2026-07-12
+
+- fix(typescript-sdk): retry trusted npm publication
+
+## [2.0.1] - 2026-07-12
+
+- fix(release): align Ruby metadata and retry npm publication
+
+## [2.0.0] - 2026-07-12
+
+- feat(sdk): harden official package release gates
+- feat(typescript-sdk): harden typed merchant contracts
+- test(sdks): align webhook conformance envelope
+- refactor(sdk): expose idiomatic camelCase contracts
+- feat(sdk): add official Merchant API clients
+- feat(ecosystem): automate SDK and plugin releases
+
+## 1.0.0
+
+- Initial official TypeScript and JavaScript SDK.
+- Invoice create, get, list, iterate, cancel, confirm, and sandbox simulation.
+- Withdrawal create, get, list, iterate, cancel, and sandbox simulation.
+- Balance retrieval.
+- HMAC-SHA256 request signing, typed RFC 9457 errors, bounded retries, and webhook verification.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Paymos Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Paymos Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,117 +1,117 @@
-# Paymos TypeScript SDK
-
-Official server-side TypeScript and JavaScript SDK for the [Paymos Merchant API](https://paymos.io/docs/quick-start).
-
-> Do not use an API secret in browser or mobile code. This package targets trusted Node.js backends and serverless runtimes with Node.js crypto support.
-
-## Install
-
-```bash
-npm install @paymos/sdk
-```
-
-Node.js 22.12 or newer is required. The package ships ESM, CommonJS, and TypeScript declarations and has no runtime dependencies.
-
-## Quick start
-
-```ts
-import { Paymos, externalOrderId } from "@paymos/sdk";
-
-const paymos = new Paymos({
-  apiKey: process.env.PAYMOS_API_KEY!,
-  apiSecret: process.env.PAYMOS_API_SECRET!,
-});
-
-const invoice = await paymos.invoices.create({
-  project_id: "prj_xxxxxxxxxxxx",
-  amount: "49.95",
-  currency: "USD",
-  external_order_id: externalOrderId("order"),
-});
-
-console.log(invoice.payment_url);
-```
-
-Use decimal strings for money. Never convert API amounts to JavaScript `number`.
-
-## List and iterate
-
-```ts
-const page = await paymos.invoices.list({
-  project_id: "prj_xxxxxxxxxxxx",
-  status: ["paid", "paid_over"],
-  limit: 50,
-});
-
-for await (const invoice of paymos.invoices.iterate({ status: ["paid"] }, 10)) {
-  console.log(invoice.invoice_id);
-}
-```
-
-The API uses opaque forward-only cursors. The second `iterate` argument is a client-side maximum page count.
-
-## Withdrawals and balances
-
-```ts
-const withdrawal = await paymos.withdrawals.create({
-  destination_address: "TRX...whitelisted...address",
-  network: "tron",
-  currency: "USDT",
-  amount: "50.00",
-  external_order_id: externalOrderId("payout"),
-});
-
-const balances = await paymos.balances.get();
-```
-
-Use a Payout key (`rk_test_...` or `rk_live_...`) for withdrawals. Destinations must already be whitelisted.
-
-## Webhooks
-
-Always verify the exact raw request body before parsing JSON:
-
-```ts
-import { WebhookVerifier } from "@paymos/sdk";
-
-const verifier = new WebhookVerifier(process.env.PAYMOS_WEBHOOK_SECRET!);
-const event = verifier.constructEvent(
-  request.headers.get("x-webhook-signature") ?? "",
-  rawBody,
-);
-
-switch (event.event_type) {
-  case "invoice.paid":
-    // Fulfil idempotently by event.event_id.
-    break;
-}
-```
-
-The verifier accepts multiple `v1` signatures during secret rotation, uses constant-time comparison, and rejects timestamps outside the default five-minute tolerance.
-
-## Errors and retries
-
-```ts
-import { RateLimitError, ValidationError } from "@paymos/sdk";
-
-try {
-  await paymos.balances.get();
-} catch (error) {
-  if (error instanceof ValidationError) console.error(error.code, error.field, error.errors);
-  if (error instanceof RateLimitError) console.error(error.retryAfterSeconds);
-  throw error;
-}
-```
-
-The SDK retries `429` responses and retries `5xx` only for idempotent methods. It never blindly retries a side-effecting POST after a server error.
-
-## Links
-
-- [API documentation](https://paymos.io/docs/quick-start)
-- [Invoices](https://paymos.io/docs/invoices/create)
-- [Withdrawals](https://paymos.io/docs/withdrawals/create)
-- [Webhooks](https://paymos.io/docs/webhooks)
-- [Issues](https://github.com/Paymos-labs/typescript-sdk/issues)
-
-## License
-
-MIT
+# Paymos TypeScript SDK
+
+Official server-side TypeScript and JavaScript SDK for the [Paymos Merchant API](https://paymos.io/docs/server-sdks).
+
+> Do not use an API secret in browser or mobile code. This package targets trusted Node.js backends and serverless runtimes with Node.js crypto support.
+
+## Install
+
+```bash
+npm install @paymos/sdk
+```
+
+Node.js 22.12 or newer is required. The package ships ESM, CommonJS, and TypeScript declarations and has no runtime dependencies.
+
+## Quick start
+
+```ts
+import { Paymos, externalOrderId } from "@paymos/sdk";
+
+const paymos = new Paymos({
+  apiKey: process.env.PAYMOS_API_KEY!,
+  apiSecret: process.env.PAYMOS_API_SECRET!,
+});
+
+const invoice = await paymos.invoices.create({
+  projectId: "prj_xxxxxxxxxxxx",
+  amount: "49.95",
+  currency: "USD",
+  externalOrderId: externalOrderId("order"),
+});
+
+console.log(invoice.paymentUrl);
+```
+
+Use decimal strings for money. Never convert API amounts to JavaScript `number`.
+
+## List and iterate
+
+```ts
+const page = await paymos.invoices.list({
+  projectId: "prj_xxxxxxxxxxxx",
+  status: ["paid", "paid_over"],
+  limit: 50,
+});
+
+for await (const invoice of paymos.invoices.iterate({ status: ["paid"] }, 10)) {
+  console.log(invoice.invoiceId);
+}
+```
+
+The API uses opaque forward-only cursors. The second `iterate` argument is a client-side maximum page count.
+
+## Withdrawals and balances
+
+```ts
+const withdrawal = await paymos.withdrawals.create({
+  destinationAddress: "TRX...whitelisted...address",
+  network: "TRC20",
+  currency: "USDT",
+  amount: "50.00",
+  externalOrderId: externalOrderId("payout"),
+});
+
+const balances = await paymos.balances.get();
+```
+
+Use a Payout key (`rk_test_...` or `rk_live_...`) for withdrawals. Destinations must already be whitelisted.
+
+## Webhooks
+
+Always verify the exact raw request body before parsing JSON:
+
+```ts
+import { WebhookVerifier } from "@paymos/sdk";
+
+const verifier = new WebhookVerifier(process.env.PAYMOS_WEBHOOK_SECRET!);
+const event = verifier.constructEvent(
+  request.headers.get("x-webhook-signature") ?? "",
+  rawBody,
+);
+
+switch (event.eventType) {
+  case "invoice.paid":
+    // Fulfil idempotently by event.eventId.
+    break;
+}
+```
+
+The verifier accepts multiple `v1` signatures during secret rotation, uses constant-time comparison, and rejects timestamps outside the default five-minute tolerance.
+
+## Errors and retries
+
+```ts
+import { RateLimitError, ValidationError } from "@paymos/sdk";
+
+try {
+  await paymos.balances.get();
+} catch (error) {
+  if (error instanceof ValidationError) console.error(error.code, error.field, error.errors);
+  if (error instanceof RateLimitError) console.error(error.retryAfterSeconds);
+  throw error;
+}
+```
+
+The SDK retries `429` responses and retries `5xx` only for idempotent methods. It never blindly retries a side-effecting POST after a server error.
+
+## Links
+
+- [API documentation](https://paymos.io/docs/server-sdks)
+- [Invoices](https://paymos.io/docs/invoices/create)
+- [Withdrawals](https://paymos.io/docs/withdrawals/create)
+- [Webhooks](https://paymos.io/docs/webhooks)
+- [Issues](https://github.com/Paymos-labs/typescript-sdk/issues)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -47,6 +47,37 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto3 = require("crypto");
 
+// src/wire.ts
+function toWire(value) {
+  return mapKeys(value, (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`));
+}
+function fromWire(value) {
+  return mapKeys(value, (key) => key.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase()));
+}
+function mapKeys(value, rename) {
+  if (Array.isArray(value)) return value.map((item) => mapKeys(item, rename));
+  if (!isPlainObject(value)) return value;
+  const mapped = {};
+  for (const [key, item] of Object.entries(value)) {
+    const mappedKey = rename(key);
+    if (Object.hasOwn(mapped, mappedKey)) {
+      throw new TypeError(`Duplicate Paymos field after case conversion: ${mappedKey}`);
+    }
+    Object.defineProperty(mapped, mappedKey, {
+      value: mapKeys(item, rename),
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+  }
+  return mapped;
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
 // src/errors.ts
 var PaymosError = class extends Error {
   constructor(message, options) {
@@ -66,8 +97,8 @@ var ApiError = class extends PaymosError {
   headers;
   problem;
   constructor(status, body, headers) {
-    const problem = parseProblem(body);
-    const detail = problem?.detail ?? problem?.errors?.[0]?.message ?? problem?.code ?? problem?.title;
+    const problem = parseProblem(status, body);
+    const detail = problem?.detail || problem?.code || problem?.title;
     super(`Paymos API ${status}: ${detail || body || "empty response"}`);
     this.status = status;
     this.body = body;
@@ -75,10 +106,10 @@ var ApiError = class extends PaymosError {
     this.problem = problem;
   }
   get code() {
-    return this.problem?.errors?.[0]?.code ?? this.problem?.code ?? "";
+    return this.problem?.code ?? "";
   }
   get field() {
-    return this.problem?.errors?.[0]?.field ?? this.problem?.field ?? null;
+    return this.problem?.field ?? null;
   }
   get errors() {
     return this.problem?.errors ?? [];
@@ -118,11 +149,13 @@ function apiErrorFromResponse(status, body, headers) {
   if (status >= 500) return new ServerError(status, body, headers);
   return new ApiError(status, body, headers);
 }
-function parseProblem(body) {
+function parseProblem(status, body) {
   if (!body) return null;
   try {
     const parsed = JSON.parse(body);
-    return parsed !== null && typeof parsed === "object" ? parsed : null;
+    if (parsed === null || typeof parsed !== "object") return null;
+    const problem = fromWire(parsed);
+    return typeof problem.type === "string" && typeof problem.title === "string" && typeof problem.status === "number" && Number.isInteger(problem.status) && problem.status === status && typeof problem.detail === "string" && typeof problem.code === "string" ? problem : null;
   } catch {
     return null;
   }
@@ -173,7 +206,7 @@ function rfc3986(value) {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "2.0.3";
 
 // src/http.ts
 var HttpClient = class {
@@ -182,7 +215,7 @@ var HttpClient = class {
     this.options = normalizeOptions(options);
   }
   async request(method, path, payload, query = "") {
-    const body = payload === void 0 ? "" : JSON.stringify(payload);
+    const body = payload === void 0 ? "" : JSON.stringify(toWire(payload));
     const url = `${this.options.baseUrl}${path}${query}`;
     let attempt = 0;
     while (true) {
@@ -224,6 +257,7 @@ var HttpClient = class {
       }
       if (shouldRetry(method, response.status) && attempt < this.options.maxRetries) {
         const retryAfter = retryAfterMs(response.headers.get("retry-after"));
+        await response.body?.cancel();
         await sleep(Math.max(backoff(this.options.baseDelayMs, ++attempt), retryAfter ?? 0));
         continue;
       }
@@ -231,7 +265,7 @@ var HttpClient = class {
       if (!response.ok) throw apiErrorFromResponse(response.status, responseBody, response.headers);
       if (responseBody === "") return {};
       try {
-        return JSON.parse(responseBody);
+        return fromWire(JSON.parse(responseBody));
       } catch (error) {
         throw new PaymosError("Paymos API returned invalid JSON.", { cause: error });
       }
@@ -309,7 +343,7 @@ var InvoicesResource = class {
     return this.http.request("GET", `/v1/invoices/${encodePathSegment(invoiceId)}`);
   }
   list(params = {}) {
-    return this.http.request("GET", "/v1/invoices", void 0, buildQuery(params));
+    return this.http.request("GET", "/v1/invoices", void 0, buildQuery(toWire(params)));
   }
   async *iterate(params = {}, maxPages = 100) {
     assertMaxPages(maxPages);
@@ -317,7 +351,7 @@ var InvoicesResource = class {
     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;
+      const next = page.nextCursor || void 0;
       if (next === void 0) return;
       if (next === cursor) throw new Error("Paymos API returned the same pagination cursor twice.");
       cursor = next;
@@ -348,7 +382,7 @@ var WithdrawalsResource = class {
     return this.http.request("GET", `/v1/withdrawals/${encodePathSegment(withdrawalId)}`);
   }
   list(params = {}) {
-    return this.http.request("GET", "/v1/withdrawals", void 0, buildQuery(params));
+    return this.http.request("GET", "/v1/withdrawals", void 0, buildQuery(toWire(params)));
   }
   async *iterate(params = {}, maxPages = 100) {
     assertMaxPages(maxPages);
@@ -356,7 +390,7 @@ var WithdrawalsResource = class {
     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;
+      const next = page.nextCursor || void 0;
       if (next === void 0) return;
       if (next === cursor) throw new Error("Paymos API returned the same pagination cursor twice.");
       cursor = next;
@@ -442,8 +476,11 @@ var WebhookVerifier = class {
   constructEvent(signatureHeader, rawBody, now = Math.floor(Date.now() / 1e3)) {
     this.assertValid(signatureHeader, rawBody, now);
     try {
-      return JSON.parse(rawBody.toString());
+      const event = fromWire(JSON.parse(rawBody.toString()));
+      assertEventEnvelope(event);
+      return event;
     } catch (error) {
+      if (error instanceof TypeError) throw error;
       throw new TypeError("Webhook payload is not valid JSON.", { cause: error });
     }
   }
@@ -451,16 +488,39 @@ var WebhookVerifier = class {
 function parseHeader(header) {
   if (typeof header !== "string") return null;
   let timestamp;
+  let timestampCount = 0;
   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 === "t" && /^\d+$/.test(value)) {
+      timestamp = Number(value);
+      timestampCount += 1;
+    }
     if (key === "v1" && value !== "") signatures.push(value);
   }
-  return timestamp === void 0 || signatures.length === 0 ? null : { timestamp, signatures };
+  return timestamp === void 0 || timestampCount !== 1 || !Number.isSafeInteger(timestamp) || signatures.length === 0 ? null : { timestamp, signatures };
+}
+function assertEventEnvelope(value) {
+  if (value === null || typeof value !== "object") throw new TypeError("Webhook payload must be an object.");
+  const event = value;
+  if (typeof event.eventId !== "string" || event.eventId.trim() === "") {
+    throw new TypeError("Webhook eventId must be a non-empty string.");
+  }
+  if (typeof event.eventType !== "string" || event.eventType.trim() === "") {
+    throw new TypeError("Webhook eventType must be a non-empty string.");
+  }
+  if (!Number.isSafeInteger(event.version) || event.version < 1) {
+    throw new TypeError("Webhook version must be a positive integer.");
+  }
+  if (!Number.isSafeInteger(event.occurredAt) || event.occurredAt < 0) {
+    throw new TypeError("Webhook occurredAt must be a non-negative Unix timestamp.");
+  }
+  if (event.data === null || typeof event.data !== "object") {
+    throw new TypeError("Webhook data must be an object.");
+  }
 }
 
 // src/index.ts