mavunta 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chainwaka Technologies
+
+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

@@ -0,0 +1,155 @@
+# mavunta
+
+Official TypeScript and JavaScript SDK for the Mavunta API.
+
+Mavunta helps merchants accept **M-Pesa, card, PayPal, Mavunta Balance, and crypto** payments, with settlement to **USDT, USDC, BTC, ETH, or SOL**. Create a payment intent, send the customer to hosted checkout, then confirm the result with signed webhooks.
+
+> Server-side only. This package uses your **secret** (`cwk_…_sk_`) or **restricted** (`cwk_…_rk_`) key and must never run in a browser.
+
+## Installation
+
+```bash
+npm install mavunta
+```
+
+`npm install mavunta` also works (it re-exports this package).
+
+## Quick start
+
+```ts
+import Mavunta from 'mavunta'
+
+const mavunta = new Mavunta({
+  secretKey: process.env.MAVUNTA_SECRET_KEY!,
+  environment: 'sandbox', // informational; the key prefix selects the mode
+})
+```
+
+## Create a payment intent
+
+```ts
+const intent = await mavunta.paymentIntents.create({
+  amount: '2500',
+  currency: 'KES',
+  settlement_currency: 'USDT',
+  payment_methods: ['mpesa', 'card', 'paypal', 'mavunta_balance'],
+  customer: { email: 'customer@example.com', phone: '+254712345678' },
+  metadata: { orderId: 'ORD-1001' },
+})
+
+// Redirect the customer to complete payment:
+return intent.checkout_url
+```
+
+## Payment links and QR
+
+```ts
+const link = await mavunta.paymentLinks.create({
+  title: 'Order #1001',
+  amount: '2500',
+  currency: 'KES',
+  settlement_currency: 'USDT',
+})
+// link.url, link.qr_code_url
+```
+
+## Verify webhooks
+
+Payment results are asynchronous (M-Pesa, card redirects, crypto confirmations), so confirm them with signed webhooks. Always use the **raw** request body.
+
+```ts
+import express from 'express'
+import Mavunta from 'mavunta'
+
+const mavunta = new Mavunta({ secretKey: process.env.MAVUNTA_SECRET_KEY! })
+
+app.post('/mavunta/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  let event
+  try {
+    event = mavunta.webhooks.verify({
+      payload: req.body, // raw Buffer
+      signature: req.headers['mavunta-signature'] as string,
+      timestamp: req.headers['mavunta-timestamp'] as string,
+      secret: process.env.MAVUNTA_WEBHOOK_SECRET!,
+    })
+  } catch {
+    return res.sendStatus(400)
+  }
+
+  if (event.type === 'payment_intent.paid') {
+    // fulfil the order (idempotently)
+  }
+  res.sendStatus(200)
+})
+```
+
+Only need verification? Import it standalone:
+
+```ts
+import { verifyWebhook } from 'mavunta/webhooks'
+```
+
+## Sandbox and live mode
+
+The key prefix selects the mode (`cwk_test_…` vs `cwk_live_…`); responses carry `environment` and `livemode`. In sandbox you can simulate events:
+
+```ts
+await mavunta.sandbox.triggerWebhook({ type: 'payment_intent.paid' })
+```
+
+## API keys
+
+| Key | Where | Can do |
+| --- | --- | --- |
+| `cwk_…_sk_` (secret) | Backend | Create and read objects |
+| `cwk_…_rk_` (restricted) | Backend | Scoped subset of the above |
+
+Never embed a secret key in a browser, mobile app, or public repo.
+
+## Idempotency
+
+Every money-moving create is retry-safe. Pass your own key, or let the SDK generate one per request:
+
+```ts
+await mavunta.paymentIntents.create(params, { idempotencyKey: 'order_1001_attempt_1' })
+```
+
+## Errors
+
+```ts
+import { MavuntaError, MavuntaValidationError } from 'mavunta'
+
+try {
+  await mavunta.paymentIntents.create(params)
+} catch (err) {
+  if (err instanceof MavuntaValidationError) {
+    console.log(err.code, err.param)
+  } else if (err instanceof MavuntaError) {
+    console.log(err.code, err.requestId, err.statusCode)
+  }
+}
+```
+
+Classes: `MavuntaError`, `MavuntaAPIError`, `MavuntaAuthenticationError`, `MavuntaPermissionError`, `MavuntaValidationError`, `MavuntaIdempotencyError`, `MavuntaRateLimitError`, `MavuntaConnectionError`, `MavuntaTimeoutError`, `MavuntaWebhookSignatureError`.
+
+## Resources
+
+`auth`, `rates`, `quotes`, `paymentIntents`, `paymentLinks`, `customers`, `refunds`, `balances`, `settlements`, `reports`, `webhookEndpoints`, `webhookEvents`, `sandbox`, `webhooks` (verify).
+
+## Security
+
+- Keep secret keys on the server and out of version control.
+- Verify every webhook signature before acting; return `2xx` quickly.
+- Treat confirmed crypto and payout events as final.
+
+## Support
+
+- Website: https://www.mavunta.com
+- Developers: https://developers.mavunta.com
+- Status: https://status.mavunta.com
+- Support: support@mavunta.com
+- Security: security@mavunta.com
+
+## License
+
+MIT © Chainwaka Technologies.

package/dist/chunk-DNIDKPOQ.js

@@ -0,0 +1,108 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+// src/webhooks/verify.ts
+
+// src/errors.ts
+var MavuntaError = class extends Error {
+  type;
+  code;
+  param;
+  requestId;
+  statusCode;
+  docsUrl;
+  constructor(message, init = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.type = init.type ?? "api_error";
+    this.code = init.code ?? "unknown";
+    this.param = init.param ?? null;
+    this.requestId = init.requestId ?? null;
+    this.statusCode = init.statusCode ?? null;
+    this.docsUrl = init.docsUrl ?? null;
+  }
+};
+var MavuntaAPIError = class extends MavuntaError {
+};
+var MavuntaAuthenticationError = class extends MavuntaError {
+};
+var MavuntaPermissionError = class extends MavuntaError {
+};
+var MavuntaValidationError = class extends MavuntaError {
+};
+var MavuntaIdempotencyError = class extends MavuntaError {
+};
+var MavuntaConnectionError = class extends MavuntaError {
+};
+var MavuntaTimeoutError = class extends MavuntaError {
+};
+var MavuntaWebhookSignatureError = class extends MavuntaError {
+};
+var MavuntaRateLimitError = class extends MavuntaError {
+  retryAfterMs;
+  constructor(message, init = {}) {
+    super(message, init);
+    this.retryAfterMs = init.retryAfterMs ?? null;
+  }
+};
+function errorFromResponse(status, body, retryAfterMs = null) {
+  const init = {
+    type: body?.type,
+    code: body?.code,
+    param: body?.param ?? null,
+    requestId: body?.request_id ?? null,
+    statusCode: status,
+    docsUrl: body?.docs_url ?? null
+  };
+  const message = body?.message ?? `Mavunta API error (HTTP ${status})`;
+  if (status === 401) return new MavuntaAuthenticationError(message, init);
+  if (status === 403) return new MavuntaPermissionError(message, init);
+  if (status === 429) return new MavuntaRateLimitError(message, { ...init, retryAfterMs });
+  if (status === 409 || body?.type === "idempotency_error")
+    return new MavuntaIdempotencyError(message, init);
+  if (status === 400 || status === 422 || body?.type === "validation_error")
+    return new MavuntaValidationError(message, init);
+  return new MavuntaAPIError(message, init);
+}
+
+// src/webhooks/verify.ts
+function fail(message) {
+  throw new MavuntaWebhookSignatureError(message, { type: "webhook_signature_error", code: "invalid_signature" });
+}
+function verifyWebhook(params) {
+  const { signature, timestamp, secret } = params;
+  if (!signature) fail("Missing Mavunta-Signature header.");
+  if (!timestamp) fail("Missing Mavunta-Timestamp header.");
+  if (!secret) fail("Missing webhook signing secret.");
+  const raw = typeof params.payload === "string" ? params.payload : params.payload.toString("utf8");
+  const tolerance = params.toleranceSec ?? 300;
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts)) fail("Invalid Mavunta-Timestamp header.");
+  if (Math.abs(Date.now() / 1e3 - ts) > tolerance) fail("Timestamp outside the tolerance window.");
+  const expected = createHmac("sha256", secret).update(`${timestamp}.${raw}`).digest("hex");
+  let a;
+  let b;
+  try {
+    a = Buffer.from(expected, "hex");
+    b = Buffer.from(signature, "hex");
+  } catch {
+    fail("Malformed signature.");
+  }
+  if (a.length !== b.length || !timingSafeEqual(a, b)) fail("Signature mismatch.");
+  return JSON.parse(raw);
+}
+
+// src/webhooks/index.ts
+var WebhooksResource = class {
+  /** Verify a webhook signature and return the parsed event, or throw. */
+  verify(params) {
+    return verifyWebhook(params);
+  }
+  /** Alias of {@link verify}, matching the wording in some platform docs. */
+  constructEvent(params) {
+    return verifyWebhook(params);
+  }
+};
+
+export { MavuntaAPIError, MavuntaAuthenticationError, MavuntaConnectionError, MavuntaError, MavuntaIdempotencyError, MavuntaPermissionError, MavuntaRateLimitError, MavuntaTimeoutError, MavuntaValidationError, MavuntaWebhookSignatureError, WebhooksResource, errorFromResponse, verifyWebhook };
+//# sourceMappingURL=chunk-DNIDKPOQ.js.map
+//# sourceMappingURL=chunk-DNIDKPOQ.js.map

package/dist/chunk-DNIDKPOQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/webhooks/verify.ts","../src/webhooks/index.ts"],"names":[],"mappings":"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","file":"chunk-DNIDKPOQ.js","sourcesContent":["/**\r\n * Error hierarchy for the Mavunta SDK.\r\n *\r\n * Every failure surfaces as a {@link MavuntaError} subclass so callers can\r\n * branch on the type and read `code` / `requestId` for support. The shape\r\n * mirrors the API's error envelope (spec §24):\r\n *\r\n *   { error: { type, code, message, param, request_id, docs_url } }\r\n */\r\n\r\nexport interface MavuntaErrorBody {\r\n  type?: string\r\n  code?: string\r\n  message?: string\r\n  param?: string | null\r\n  request_id?: string\r\n  docs_url?: string\r\n}\r\n\r\nexport interface MavuntaErrorInit {\r\n  type?: string\r\n  code?: string\r\n  param?: string | null\r\n  requestId?: string | null\r\n  statusCode?: number | null\r\n  docsUrl?: string | null\r\n}\r\n\r\n/** Base class for everything thrown by the SDK. */\r\nexport class MavuntaError extends Error {\r\n  readonly type: string\r\n  readonly code: string\r\n  readonly param: string | null\r\n  readonly requestId: string | null\r\n  readonly statusCode: number | null\r\n  readonly docsUrl: string | null\r\n\r\n  constructor(message: string, init: MavuntaErrorInit = {}) {\r\n    super(message)\r\n    this.name = this.constructor.name\r\n    this.type = init.type ?? 'api_error'\r\n    this.code = init.code ?? 'unknown'\r\n    this.param = init.param ?? null\r\n    this.requestId = init.requestId ?? null\r\n    this.statusCode = init.statusCode ?? null\r\n    this.docsUrl = init.docsUrl ?? null\r\n  }\r\n}\r\n\r\n/** A non-2xx response that does not map to a more specific class. */\r\nexport class MavuntaAPIError extends MavuntaError {}\r\n/** 401: missing, invalid, or revoked API key. */\r\nexport class MavuntaAuthenticationError extends MavuntaError {}\r\n/** 403: the key is valid but lacks the scope for this action. */\r\nexport class MavuntaPermissionError extends MavuntaError {}\r\n/** 400 / 422: the request was malformed or failed validation. */\r\nexport class MavuntaValidationError extends MavuntaError {}\r\n/** 409 on a money-moving create with a reused idempotency key. */\r\nexport class MavuntaIdempotencyError extends MavuntaError {}\r\n/** A network failure before a response was received. */\r\nexport class MavuntaConnectionError extends MavuntaError {}\r\n/** The request exceeded the configured timeout. */\r\nexport class MavuntaTimeoutError extends MavuntaError {}\r\n/** Webhook signature verification failed. */\r\nexport class MavuntaWebhookSignatureError extends MavuntaError {}\r\n\r\n/** 429: too many requests. `retryAfterMs` is parsed from `retry-after`. */\r\nexport class MavuntaRateLimitError extends MavuntaError {\r\n  readonly retryAfterMs: number | null\r\n  constructor(message: string, init: MavuntaErrorInit & { retryAfterMs?: number | null } = {}) {\r\n    super(message, init)\r\n    this.retryAfterMs = init.retryAfterMs ?? null\r\n  }\r\n}\r\n\r\n/**\r\n * Build the right error subclass from an HTTP status + the parsed body. Used by\r\n * the client for every non-2xx response.\r\n */\r\nexport function errorFromResponse(\r\n  status: number,\r\n  body: MavuntaErrorBody | null,\r\n  retryAfterMs: number | null = null,\r\n): MavuntaError {\r\n  const init: MavuntaErrorInit = {\r\n    type: body?.type,\r\n    code: body?.code,\r\n    param: body?.param ?? null,\r\n    requestId: body?.request_id ?? null,\r\n    statusCode: status,\r\n    docsUrl: body?.docs_url ?? null,\r\n  }\r\n  const message = body?.message ?? `Mavunta API error (HTTP ${status})`\r\n\r\n  if (status === 401) return new MavuntaAuthenticationError(message, init)\r\n  if (status === 403) return new MavuntaPermissionError(message, init)\r\n  if (status === 429) return new MavuntaRateLimitError(message, { ...init, retryAfterMs })\r\n  if (status === 409 || body?.type === 'idempotency_error')\r\n    return new MavuntaIdempotencyError(message, init)\r\n  if (status === 400 || status === 422 || body?.type === 'validation_error')\r\n    return new MavuntaValidationError(message, init)\r\n  return new MavuntaAPIError(message, init)\r\n}\r\n","import { createHmac, timingSafeEqual } from 'node:crypto'\r\nimport { MavuntaWebhookSignatureError } from '../errors.js'\r\nimport type { WebhookEvent } from '../types.js'\r\n\r\nexport interface VerifyWebhookParams {\r\n  /** The raw request body, exactly as received (string or Buffer). Never the\r\n   *  parsed JSON object: re-serializing changes the bytes and breaks the HMAC. */\r\n  payload: string | Buffer\r\n  /** The `Mavunta-Signature` header (hex HMAC-SHA256). */\r\n  signature: string\r\n  /** The `Mavunta-Timestamp` header (unix seconds). */\r\n  timestamp: string\r\n  /** The endpoint's signing secret (`whsec_…`). */\r\n  secret: string\r\n  /** Reject timestamps older/newer than this many seconds (default 300). */\r\n  toleranceSec?: number\r\n}\r\n\r\nfunction fail(message: string): never {\r\n  throw new MavuntaWebhookSignatureError(message, { type: 'webhook_signature_error', code: 'invalid_signature' })\r\n}\r\n\r\n/**\r\n * Verify a webhook signature and return the parsed event, or throw a\r\n * {@link MavuntaWebhookSignatureError}.\r\n *\r\n * The signature is HMAC-SHA256 (hex) over `\"<timestamp>.<rawBody>\"`, where\r\n * `timestamp` is the `Mavunta-Timestamp` header and the digest is the\r\n * `Mavunta-Signature` header. Always pass the raw body, not parsed JSON.\r\n */\r\nexport function verifyWebhook(params: VerifyWebhookParams): WebhookEvent {\r\n  const { signature, timestamp, secret } = params\r\n  if (!signature) fail('Missing Mavunta-Signature header.')\r\n  if (!timestamp) fail('Missing Mavunta-Timestamp header.')\r\n  if (!secret) fail('Missing webhook signing secret.')\r\n\r\n  const raw = typeof params.payload === 'string' ? params.payload : params.payload.toString('utf8')\r\n  const tolerance = params.toleranceSec ?? 300\r\n\r\n  const ts = Number(timestamp)\r\n  if (!Number.isFinite(ts)) fail('Invalid Mavunta-Timestamp header.')\r\n  if (Math.abs(Date.now() / 1000 - ts) > tolerance) fail('Timestamp outside the tolerance window.')\r\n\r\n  const expected = createHmac('sha256', secret).update(`${timestamp}.${raw}`).digest('hex')\r\n  let a: Buffer\r\n  let b: Buffer\r\n  try {\r\n    a = Buffer.from(expected, 'hex')\r\n    b = Buffer.from(signature, 'hex')\r\n  } catch {\r\n    fail('Malformed signature.')\r\n  }\r\n  if (a.length !== b.length || !timingSafeEqual(a, b)) fail('Signature mismatch.')\r\n\r\n  return JSON.parse(raw) as WebhookEvent\r\n}\r\n","import { verifyWebhook, type VerifyWebhookParams } from './verify.js'\nimport type { WebhookEvent } from '../types.js'\n\nexport { verifyWebhook } from './verify.js'\nexport type { VerifyWebhookParams } from './verify.js'\n\n/**\n * Webhook helpers, available both as `mavunta.webhooks` and standalone via the\n * `mavunta/webhooks` subpath (handy when you only need verification and\n * not a full client).\n */\nexport class WebhooksResource {\n  /** Verify a webhook signature and return the parsed event, or throw. */\n  verify(params: VerifyWebhookParams): WebhookEvent {\n    return verifyWebhook(params)\n  }\n  /** Alias of {@link verify}, matching the wording in some platform docs. */\n  constructEvent(params: VerifyWebhookParams): WebhookEvent {\n    return verifyWebhook(params)\n  }\n}\n"]}

package/dist/index-C_GLtIgI.d.cts

@@ -0,0 +1,192 @@
+/** Shared types for the Mavunta SDK. Resource payloads are pragmatic subsets:
+ *  unknown fields pass through, so a forward-compatible API never breaks a build. */
+type MavuntaEnvironment = 'sandbox' | 'live';
+interface MavuntaOptions {
+    /** Your secret (`cwk_…_sk_`) or restricted (`cwk_…_rk_`) key. Never a public key. */
+    secretKey: string;
+    /** Informational; the key prefix selects test vs live server-side. */
+    environment?: MavuntaEnvironment;
+    /** Override the API base URL (default `https://api.mavunta.com/v1`). */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 30000). */
+    timeoutMs?: number;
+    /** Max automatic retries for safe/idempotent requests (default 2). */
+    maxRetries?: number;
+}
+/** Per-call options for money-moving create requests. */
+interface RequestOptions {
+    /** Replaying the same key returns the original result instead of acting twice. */
+    idempotencyKey?: string;
+}
+interface ListResponse<T> {
+    object: 'list';
+    data: T[];
+    has_more: boolean;
+}
+interface EnvelopeFields {
+    request_id?: string;
+    environment?: MavuntaEnvironment;
+    livemode?: boolean;
+}
+type SettlementCurrency = 'USDT' | 'USDC' | 'BTC' | 'ETH' | 'SOL';
+type PaymentMethod = 'mavunta_balance' | 'mpesa' | 'card' | 'paypal' | 'external_wallet';
+interface PaymentIntent extends EnvelopeFields {
+    id: string;
+    object?: 'payment_intent';
+    status: string;
+    amount: string;
+    currency: string;
+    settlement_currency: string;
+    pay_amount: string | null;
+    pay_asset?: string;
+    checkout_url: string;
+    merchant_reference: string | null;
+    description: string | null;
+    metadata: Record<string, unknown> | null;
+    expires_at: string;
+}
+interface CreatePaymentIntentParams {
+    amount: string;
+    currency: string;
+    settlement_currency?: SettlementCurrency;
+    description?: string;
+    merchant_reference?: string;
+    payment_methods?: PaymentMethod[];
+    customer?: {
+        id?: string;
+        email?: string;
+        phone?: string;
+    };
+    metadata?: Record<string, unknown>;
+    expires_in_minutes?: number;
+}
+interface PaymentLink extends EnvelopeFields {
+    id: string;
+    object: 'payment_link';
+    url: string;
+    qr_code_url?: string;
+    status: string;
+    paid_count: number;
+    max_payments: number | null;
+}
+interface CreatePaymentLinkParams {
+    title: string;
+    currency: string;
+    amount?: string;
+    settlement_currency?: SettlementCurrency;
+    description?: string;
+    max_payments?: number;
+    expires_at?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Refund extends EnvelopeFields {
+    id: string;
+    object: 'refund';
+    payment_intent: string;
+    amount: string;
+    asset: string;
+    status: 'requested' | 'succeeded' | 'failed';
+    reason: string | null;
+    created_at: string;
+}
+interface Customer extends EnvelopeFields {
+    id: string;
+    object: 'customer';
+    email: string | null;
+    phone: string | null;
+    name: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+interface CreateCustomerParams {
+    email?: string;
+    phone?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Balance extends EnvelopeFields {
+    object: 'balance';
+    available: Array<{
+        asset: string;
+        amount: string;
+    }>;
+    pending: Array<{
+        asset: string;
+        amount: string;
+    }>;
+}
+interface Settlement extends EnvelopeFields {
+    id: string;
+    object: 'settlement';
+    asset: string;
+    amount: string;
+    status: string;
+    created_at: string;
+}
+interface WebhookEndpoint extends EnvelopeFields {
+    id: string;
+    object: 'webhook_endpoint';
+    url: string;
+    enabled_events: string[];
+    status: string;
+    secret?: string;
+    created_at: string;
+}
+interface CreateWebhookEndpointParams {
+    url: string;
+    enabled_events?: string[];
+    description?: string;
+}
+interface WebhookEvent extends EnvelopeFields {
+    id: string;
+    object: 'event';
+    type: string;
+    api_version: string;
+    created_at: string;
+    data: Record<string, unknown>;
+}
+interface AuthVerifyResult extends EnvelopeFields {
+    merchant_id: string;
+    app_id: string | null;
+    key_id: string;
+    scopes: string[];
+    ip_allowed: boolean;
+    status: string;
+}
+
+interface VerifyWebhookParams {
+    /** The raw request body, exactly as received (string or Buffer). Never the
+     *  parsed JSON object: re-serializing changes the bytes and breaks the HMAC. */
+    payload: string | Buffer;
+    /** The `Mavunta-Signature` header (hex HMAC-SHA256). */
+    signature: string;
+    /** The `Mavunta-Timestamp` header (unix seconds). */
+    timestamp: string;
+    /** The endpoint's signing secret (`whsec_…`). */
+    secret: string;
+    /** Reject timestamps older/newer than this many seconds (default 300). */
+    toleranceSec?: number;
+}
+/**
+ * Verify a webhook signature and return the parsed event, or throw a
+ * {@link MavuntaWebhookSignatureError}.
+ *
+ * The signature is HMAC-SHA256 (hex) over `"<timestamp>.<rawBody>"`, where
+ * `timestamp` is the `Mavunta-Timestamp` header and the digest is the
+ * `Mavunta-Signature` header. Always pass the raw body, not parsed JSON.
+ */
+declare function verifyWebhook(params: VerifyWebhookParams): WebhookEvent;
+
+/**
+ * Webhook helpers, available both as `mavunta.webhooks` and standalone via the
+ * `mavunta/webhooks` subpath (handy when you only need verification and
+ * not a full client).
+ */
+declare class WebhooksResource {
+    /** Verify a webhook signature and return the parsed event, or throw. */
+    verify(params: VerifyWebhookParams): WebhookEvent;
+    /** Alias of {@link verify}, matching the wording in some platform docs. */
+    constructEvent(params: VerifyWebhookParams): WebhookEvent;
+}
+
+export { type AuthVerifyResult as A, type Balance as B, type CreatePaymentIntentParams as C, type ListResponse as L, type MavuntaOptions as M, type PaymentIntent as P, type RequestOptions as R, type Settlement as S, type VerifyWebhookParams as V, type WebhookEndpoint as W, type CreatePaymentLinkParams as a, type PaymentLink as b, type CreateCustomerParams as c, type Customer as d, type Refund as e, type CreateWebhookEndpointParams as f, type WebhookEvent as g, WebhooksResource as h, type MavuntaEnvironment as i, type PaymentMethod as j, type SettlementCurrency as k, verifyWebhook as v };

package/dist/index-C_GLtIgI.d.ts

@@ -0,0 +1,192 @@
+/** Shared types for the Mavunta SDK. Resource payloads are pragmatic subsets:
+ *  unknown fields pass through, so a forward-compatible API never breaks a build. */
+type MavuntaEnvironment = 'sandbox' | 'live';
+interface MavuntaOptions {
+    /** Your secret (`cwk_…_sk_`) or restricted (`cwk_…_rk_`) key. Never a public key. */
+    secretKey: string;
+    /** Informational; the key prefix selects test vs live server-side. */
+    environment?: MavuntaEnvironment;
+    /** Override the API base URL (default `https://api.mavunta.com/v1`). */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 30000). */
+    timeoutMs?: number;
+    /** Max automatic retries for safe/idempotent requests (default 2). */
+    maxRetries?: number;
+}
+/** Per-call options for money-moving create requests. */
+interface RequestOptions {
+    /** Replaying the same key returns the original result instead of acting twice. */
+    idempotencyKey?: string;
+}
+interface ListResponse<T> {
+    object: 'list';
+    data: T[];
+    has_more: boolean;
+}
+interface EnvelopeFields {
+    request_id?: string;
+    environment?: MavuntaEnvironment;
+    livemode?: boolean;
+}
+type SettlementCurrency = 'USDT' | 'USDC' | 'BTC' | 'ETH' | 'SOL';
+type PaymentMethod = 'mavunta_balance' | 'mpesa' | 'card' | 'paypal' | 'external_wallet';
+interface PaymentIntent extends EnvelopeFields {
+    id: string;
+    object?: 'payment_intent';
+    status: string;
+    amount: string;
+    currency: string;
+    settlement_currency: string;
+    pay_amount: string | null;
+    pay_asset?: string;
+    checkout_url: string;
+    merchant_reference: string | null;
+    description: string | null;
+    metadata: Record<string, unknown> | null;
+    expires_at: string;
+}
+interface CreatePaymentIntentParams {
+    amount: string;
+    currency: string;
+    settlement_currency?: SettlementCurrency;
+    description?: string;
+    merchant_reference?: string;
+    payment_methods?: PaymentMethod[];
+    customer?: {
+        id?: string;
+        email?: string;
+        phone?: string;
+    };
+    metadata?: Record<string, unknown>;
+    expires_in_minutes?: number;
+}
+interface PaymentLink extends EnvelopeFields {
+    id: string;
+    object: 'payment_link';
+    url: string;
+    qr_code_url?: string;
+    status: string;
+    paid_count: number;
+    max_payments: number | null;
+}
+interface CreatePaymentLinkParams {
+    title: string;
+    currency: string;
+    amount?: string;
+    settlement_currency?: SettlementCurrency;
+    description?: string;
+    max_payments?: number;
+    expires_at?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Refund extends EnvelopeFields {
+    id: string;
+    object: 'refund';
+    payment_intent: string;
+    amount: string;
+    asset: string;
+    status: 'requested' | 'succeeded' | 'failed';
+    reason: string | null;
+    created_at: string;
+}
+interface Customer extends EnvelopeFields {
+    id: string;
+    object: 'customer';
+    email: string | null;
+    phone: string | null;
+    name: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+interface CreateCustomerParams {
+    email?: string;
+    phone?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Balance extends EnvelopeFields {
+    object: 'balance';
+    available: Array<{
+        asset: string;
+        amount: string;
+    }>;
+    pending: Array<{
+        asset: string;
+        amount: string;
+    }>;
+}
+interface Settlement extends EnvelopeFields {
+    id: string;
+    object: 'settlement';
+    asset: string;
+    amount: string;
+    status: string;
+    created_at: string;
+}
+interface WebhookEndpoint extends EnvelopeFields {
+    id: string;
+    object: 'webhook_endpoint';
+    url: string;
+    enabled_events: string[];
+    status: string;
+    secret?: string;
+    created_at: string;
+}
+interface CreateWebhookEndpointParams {
+    url: string;
+    enabled_events?: string[];
+    description?: string;
+}
+interface WebhookEvent extends EnvelopeFields {
+    id: string;
+    object: 'event';
+    type: string;
+    api_version: string;
+    created_at: string;
+    data: Record<string, unknown>;
+}
+interface AuthVerifyResult extends EnvelopeFields {
+    merchant_id: string;
+    app_id: string | null;
+    key_id: string;
+    scopes: string[];
+    ip_allowed: boolean;
+    status: string;
+}
+
+interface VerifyWebhookParams {
+    /** The raw request body, exactly as received (string or Buffer). Never the
+     *  parsed JSON object: re-serializing changes the bytes and breaks the HMAC. */
+    payload: string | Buffer;
+    /** The `Mavunta-Signature` header (hex HMAC-SHA256). */
+    signature: string;
+    /** The `Mavunta-Timestamp` header (unix seconds). */
+    timestamp: string;
+    /** The endpoint's signing secret (`whsec_…`). */
+    secret: string;
+    /** Reject timestamps older/newer than this many seconds (default 300). */
+    toleranceSec?: number;
+}
+/**
+ * Verify a webhook signature and return the parsed event, or throw a
+ * {@link MavuntaWebhookSignatureError}.
+ *
+ * The signature is HMAC-SHA256 (hex) over `"<timestamp>.<rawBody>"`, where
+ * `timestamp` is the `Mavunta-Timestamp` header and the digest is the
+ * `Mavunta-Signature` header. Always pass the raw body, not parsed JSON.
+ */
+declare function verifyWebhook(params: VerifyWebhookParams): WebhookEvent;
+
+/**
+ * Webhook helpers, available both as `mavunta.webhooks` and standalone via the
+ * `mavunta/webhooks` subpath (handy when you only need verification and
+ * not a full client).
+ */
+declare class WebhooksResource {
+    /** Verify a webhook signature and return the parsed event, or throw. */
+    verify(params: VerifyWebhookParams): WebhookEvent;
+    /** Alias of {@link verify}, matching the wording in some platform docs. */
+    constructEvent(params: VerifyWebhookParams): WebhookEvent;
+}
+
+export { type AuthVerifyResult as A, type Balance as B, type CreatePaymentIntentParams as C, type ListResponse as L, type MavuntaOptions as M, type PaymentIntent as P, type RequestOptions as R, type Settlement as S, type VerifyWebhookParams as V, type WebhookEndpoint as W, type CreatePaymentLinkParams as a, type PaymentLink as b, type CreateCustomerParams as c, type Customer as d, type Refund as e, type CreateWebhookEndpointParams as f, type WebhookEvent as g, WebhooksResource as h, type MavuntaEnvironment as i, type PaymentMethod as j, type SettlementCurrency as k, verifyWebhook as v };