@monigo/sdk 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -68,6 +68,22 @@ export declare interface CreatePlanRequest {
     prices?: CreatePriceRequest[];
 }
 
+/** Request body for `portalTokens.create()`. */
+export declare interface CreatePortalTokenRequest {
+    /**
+     * The `external_id` you assigned this customer when you called
+     * `customers.create()`.
+     */
+    customer_external_id: string;
+    /** Optional human-readable label, e.g. `"Main portal link"`. */
+    label?: string;
+    /**
+     * Optional RFC 3339 expiry timestamp. Omit to create a permanent link.
+     * Example: `"2027-01-01T00:00:00Z"`
+     */
+    expires_at?: string;
+}
+
 /** Describes a price to attach when creating a plan. */
 export declare interface CreatePriceRequest {
     /** UUID of the metric this price is based on. */
@@ -93,6 +109,28 @@ export declare interface CreateSubscriptionRequest {
     plan_id: string;
 }
 
+/** Request body for `wallets.createVirtualAccount()`. */
+export declare interface CreateVirtualAccountRequest {
+    /** Use `VirtualAccountProvider` constants. */
+    provider: VirtualAccountProviderValue;
+    currency: string;
+}
+
+/** Request body for `wallets.credit()`. */
+export declare interface CreditWalletRequest {
+    /** Amount as a decimal string, e.g. `"100.50"`. */
+    amount: string;
+    currency: string;
+    description: string;
+    /** Use `WalletEntryType` constants. */
+    entry_type: WalletEntryTypeValue;
+    reference_type: string;
+    reference_id: string;
+    idempotency_key: string;
+    /** Optional provider account UUID for the other side of double entry. */
+    provider_id?: string;
+}
+
 /** An end-customer record in your Monigo organisation. */
 export declare interface Customer {
     id: string;
@@ -163,6 +201,33 @@ export declare class CustomersResource {
     delete(customerId: string): Promise<void>;
 }
 
+/** A prepaid balance belonging to a single customer. All monetary values are decimal strings. */
+export declare interface CustomerWallet {
+    id: string;
+    customer_id: string;
+    org_id: string;
+    currency: string;
+    /** Current available balance as a decimal string, e.g. `"500.000000"`. */
+    balance: string;
+    /** Balance reserved for pending operations. */
+    reserved_balance: string;
+    created_at: string;
+    updated_at: string;
+}
+
+/** Request body for `wallets.debit()`. */
+export declare interface DebitWalletRequest {
+    /** Amount as a decimal string, e.g. `"50.25"`. */
+    amount: string;
+    currency: string;
+    description: string;
+    /** Use `WalletEntryType` constants. */
+    entry_type: WalletEntryTypeValue;
+    reference_type: string;
+    reference_id: string;
+    idempotency_key: string;
+}
+
 /** Tracks the progress of an asynchronous event replay job. */
 export declare interface EventReplayJob {
     id: string;
@@ -247,6 +312,13 @@ export declare class EventsResource {
     getReplay(jobId: string): Promise<EventReplayJob>;
 }
 
+/** Request body for `wallets.getOrCreate()`. */
+export declare interface GetOrCreateWalletRequest {
+    org_id: string;
+    customer_id: string;
+    currency: string;
+}
+
 /** A single usage event sent to the Monigo ingestion pipeline. */
 export declare interface IngestEvent {
     /**
@@ -390,6 +462,32 @@ export declare const InvoiceStatus: {
 
 export declare type InvoiceStatusValue = (typeof InvoiceStatus)[keyof typeof InvoiceStatus];
 
+/** One side of a double-entry accounting record. */
+export declare interface LedgerEntry {
+    id: string;
+    org_id: string;
+    transaction_id: string;
+    wallet_id: string | null;
+    /** `customer_wallet`, `provider`, or `revenue`. */
+    account_type: string;
+    account_id: string;
+    /** Use `WalletDirection` constants. */
+    direction: WalletDirectionValue;
+    /** Amount as a decimal string. */
+    amount: string;
+    currency: string;
+    balance_before: string;
+    balance_after: string;
+    description: string;
+    /** Use `WalletEntryType` constants. */
+    entry_type: WalletEntryTypeValue;
+    reference_type: string;
+    reference_id: string;
+    idempotency_key: string;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+
 export declare interface ListCustomersResponse {
     customers: Customer[];
     count: number;
@@ -422,6 +520,11 @@ export declare interface ListPlansResponse {
     count: number;
 }
 
+export declare interface ListPortalTokensResponse {
+    tokens: PortalToken[];
+    count: number;
+}
+
 export declare interface ListSubscriptionsParams {
     /** Filter to a specific customer UUID. */
     customer_id?: string;
@@ -436,6 +539,34 @@ export declare interface ListSubscriptionsResponse {
     count: number;
 }
 
+export declare interface ListTransactionsParams {
+    /** Number of entries to return (1–100). Defaults to 25. */
+    limit?: number;
+    /** Number of entries to skip. Defaults to 0. */
+    offset?: number;
+}
+
+export declare interface ListTransactionsResponse {
+    transactions: LedgerEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+export declare interface ListVirtualAccountsResponse {
+    virtual_accounts: VirtualAccount[];
+    count: number;
+}
+
+export declare interface ListWalletsParams {
+    org_id: string;
+}
+
+export declare interface ListWalletsResponse {
+    wallets: CustomerWallet[];
+    count: number;
+}
+
 /** Defines what usage is counted and how. */
 export declare interface Metric {
     id: string;
@@ -576,6 +707,10 @@ export declare class MonigoClient {
     readonly invoices: InvoicesResource;
     /** Query aggregated usage rollups per customer and metric. Requires `read` scope. */
     readonly usage: UsageResource;
+    /** Manage customer portal access links. Requires `read` / `write` scope. */
+    readonly portalTokens: PortalTokensResource;
+    /** Manage customer wallets, balance operations, and virtual accounts. Requires `read` / `write` scope. */
+    readonly wallets: WalletsResource;
     constructor(options: MonigoClientOptions);
     /* Excluded from this release type: _request */
     /** Normalise a `Date | string` value to an ISO 8601 string. */
@@ -799,6 +934,77 @@ export declare const PlanType: {
 
 export declare type PlanTypeValue = (typeof PlanType)[keyof typeof PlanType];
 
+/**
+ * A portal token grants an end-customer read-only access to their invoices,
+ * payout slips, subscriptions, and payout accounts in the Monigo hosted portal.
+ */
+export declare interface PortalToken {
+    id: string;
+    org_id: string;
+    customer_id: string;
+    /** The opaque 64-character hex token embedded in the portal URL. */
+    token: string;
+    label: string;
+    /** ISO 8601 expiry timestamp, or `null` for a permanent link. */
+    expires_at: string | null;
+    /** ISO 8601 revocation timestamp, or `null` if still active. */
+    revoked_at: string | null;
+    created_at: string;
+    updated_at: string;
+    /** Fully-qualified URL to share with the customer, e.g. `https://app.monigo.co/portal/<token>`. */
+    portal_url: string;
+}
+
+/**
+ * Manage customer portal access links.
+ *
+ * Portal tokens grant an end-customer read-only access to their invoices,
+ * payout slips, subscriptions, and payout accounts in the Monigo hosted portal.
+ * All operations require a write-scoped API key; the organisation is inferred
+ * automatically from the key.
+ */
+export declare class PortalTokensResource {
+    private readonly client;
+    constructor(client: MonigoClient);
+    /**
+     * Generate a new portal link for a customer.
+     *
+     * **Requires `write` scope.**
+     *
+     * The returned `portal_url` is what you share with your customer — embed it
+     * in an email, open it in an iframe, or redirect the browser to it directly.
+     *
+     * @example
+     * ```ts
+     * const { portal_url } = await monigo.portalTokens.create({
+     *   customer_external_id: 'usr_abc123',
+     *   label: 'March 2026 invoice link',
+     * })
+     * await sendEmail(customer.email, { portalLink: portal_url })
+     * ```
+     */
+    create(request: CreatePortalTokenRequest, options?: MutationOptions): Promise<PortalToken>;
+    /**
+     * List all portal tokens for a customer.
+     *
+     * **Requires `read` scope.**
+     *
+     * @param customerId - The customer's Monigo UUID or their `external_id`.
+     */
+    list(customerId: string): Promise<ListPortalTokensResponse>;
+    /**
+     * Immediately revoke a portal token.
+     *
+     * **Requires `write` scope.**
+     *
+     * Any customer holding the corresponding URL will receive a 401 on their
+     * next request. This action is irreversible.
+     *
+     * @param tokenId - The UUID of the portal token record (not the raw token string).
+     */
+    revoke(tokenId: string, options?: MutationOptions): Promise<void>;
+}
+
 /** A pricing rule attached to a plan. */
 export declare interface Price {
     id: string;
@@ -1048,4 +1254,127 @@ export declare interface UsageRollup {
     updated_at: string;
 }
 
+/** A dedicated virtual bank account that funds a customer wallet. */
+export declare interface VirtualAccount {
+    id: string;
+    customer_id: string;
+    wallet_id: string;
+    org_id: string;
+    /** Payment provider. Use `VirtualAccountProvider` constants. */
+    provider: VirtualAccountProviderValue;
+    account_number: string;
+    account_name: string;
+    bank_name: string;
+    bank_code: string;
+    currency: string;
+    provider_ref: string;
+    is_active: boolean;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+}
+
+export declare const VirtualAccountProvider: {
+    readonly Paystack: "paystack";
+    readonly Flutterwave: "flutterwave";
+    readonly Monnify: "monnify";
+};
+
+export declare type VirtualAccountProviderValue = (typeof VirtualAccountProvider)[keyof typeof VirtualAccountProvider];
+
+export declare const WalletDirection: {
+    /** Reduces the wallet balance. */
+    readonly Debit: "debit";
+    /** Increases the wallet balance. */
+    readonly Credit: "credit";
+};
+
+export declare type WalletDirectionValue = (typeof WalletDirection)[keyof typeof WalletDirection];
+
+export declare const WalletEntryType: {
+    /** Credit from an external funding source. */
+    readonly Deposit: "deposit";
+    /** Debit to an external destination. */
+    readonly Withdrawal: "withdrawal";
+    /** Automatic debit for metered usage charges. */
+    readonly Usage: "usage";
+    /** Credit reversing a previous charge. */
+    readonly Refund: "refund";
+    /** Manual balance correction. */
+    readonly Adjustment: "adjustment";
+};
+
+export declare type WalletEntryTypeValue = (typeof WalletEntryType)[keyof typeof WalletEntryType];
+
+export declare interface WalletOperationResponse {
+    wallet: CustomerWallet;
+    ledger_entries: LedgerEntry[];
+}
+
+/** Manage customer wallets, balance operations, and virtual accounts. */
+export declare class WalletsResource {
+    private readonly client;
+    constructor(client: MonigoClient);
+    /**
+     * Get an existing wallet or create a new one for the given customer and currency.
+     *
+     * **Requires `write` scope.**
+     */
+    getOrCreate(request: GetOrCreateWalletRequest, options?: MutationOptions): Promise<CustomerWallet>;
+    /**
+     * List all wallets for an organisation.
+     *
+     * **Requires `read` scope.**
+     */
+    list(params: ListWalletsParams): Promise<ListWalletsResponse>;
+    /**
+     * List all wallets belonging to a specific customer.
+     *
+     * **Requires `read` scope.**
+     */
+    listByCustomer(customerId: string): Promise<ListWalletsResponse>;
+    /**
+     * Fetch a single wallet by UUID, including its virtual accounts.
+     *
+     * **Requires `read` scope.**
+     */
+    get(walletId: string): Promise<WalletWithVirtualAccountsResponse>;
+    /**
+     * Credit (add funds to) a wallet. Returns the updated wallet and ledger entries.
+     *
+     * **Requires `write` scope.**
+     */
+    credit(walletId: string, request: CreditWalletRequest, options?: MutationOptions): Promise<WalletOperationResponse>;
+    /**
+     * Debit (remove funds from) a wallet. Returns the updated wallet and ledger entries.
+     * Throws a 402 error if the wallet has insufficient balance.
+     *
+     * **Requires `write` scope.**
+     */
+    debit(walletId: string, request: DebitWalletRequest, options?: MutationOptions): Promise<WalletOperationResponse>;
+    /**
+     * List paginated ledger entries (transactions) for a wallet.
+     *
+     * **Requires `read` scope.**
+     */
+    listTransactions(walletId: string, params?: ListTransactionsParams): Promise<ListTransactionsResponse>;
+    /**
+     * Create a dedicated virtual bank account that automatically funds the wallet on deposit.
+     *
+     * **Requires `write` scope.**
+     */
+    createVirtualAccount(walletId: string, request: CreateVirtualAccountRequest, options?: MutationOptions): Promise<VirtualAccount>;
+    /**
+     * List all virtual accounts linked to a wallet.
+     *
+     * **Requires `read` scope.**
+     */
+    listVirtualAccounts(walletId: string): Promise<ListVirtualAccountsResponse>;
+}
+
+export declare interface WalletWithVirtualAccountsResponse {
+    wallet: CustomerWallet;
+    virtual_accounts: VirtualAccount[];
+}
+
 export { }

package/dist/monigo.cjs

@@ -663,6 +663,183 @@ class UsageResource {
     return this.client._request("GET", "/v1/usage", { query });
   }
 }
+class PortalTokensResource {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Generate a new portal link for a customer.
+   *
+   * **Requires `write` scope.**
+   *
+   * The returned `portal_url` is what you share with your customer — embed it
+   * in an email, open it in an iframe, or redirect the browser to it directly.
+   *
+   * @example
+   * ```ts
+   * const { portal_url } = await monigo.portalTokens.create({
+   *   customer_external_id: 'usr_abc123',
+   *   label: 'March 2026 invoice link',
+   * })
+   * await sendEmail(customer.email, { portalLink: portal_url })
+   * ```
+   */
+  async create(request, options) {
+    const wrapper = await this.client._request(
+      "POST",
+      "/v1/portal/tokens",
+      { body: request, idempotencyKey: options?.idempotencyKey }
+    );
+    return wrapper.token;
+  }
+  /**
+   * List all portal tokens for a customer.
+   *
+   * **Requires `read` scope.**
+   *
+   * @param customerId - The customer's Monigo UUID or their `external_id`.
+   */
+  async list(customerId) {
+    return this.client._request(
+      "GET",
+      "/v1/portal/tokens",
+      { query: { customer_id: customerId } }
+    );
+  }
+  /**
+   * Immediately revoke a portal token.
+   *
+   * **Requires `write` scope.**
+   *
+   * Any customer holding the corresponding URL will receive a 401 on their
+   * next request. This action is irreversible.
+   *
+   * @param tokenId - The UUID of the portal token record (not the raw token string).
+   */
+  async revoke(tokenId, options) {
+    await this.client._request(
+      "DELETE",
+      `/v1/portal/tokens/${tokenId}`,
+      { idempotencyKey: options?.idempotencyKey }
+    );
+  }
+}
+class WalletsResource {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get an existing wallet or create a new one for the given customer and currency.
+   *
+   * **Requires `write` scope.**
+   */
+  async getOrCreate(request, options) {
+    const wrapper = await this.client._request(
+      "POST",
+      "/v1/wallets",
+      { body: request, idempotencyKey: options?.idempotencyKey }
+    );
+    return wrapper.wallet;
+  }
+  /**
+   * List all wallets for an organisation.
+   *
+   * **Requires `read` scope.**
+   */
+  async list(params) {
+    return this.client._request("GET", "/v1/wallets", {
+      query: { org_id: params.org_id }
+    });
+  }
+  /**
+   * List all wallets belonging to a specific customer.
+   *
+   * **Requires `read` scope.**
+   */
+  async listByCustomer(customerId) {
+    return this.client._request(
+      "GET",
+      `/v1/customers/${customerId}/wallets`
+    );
+  }
+  /**
+   * Fetch a single wallet by UUID, including its virtual accounts.
+   *
+   * **Requires `read` scope.**
+   */
+  async get(walletId) {
+    return this.client._request(
+      "GET",
+      `/v1/wallets/${walletId}`
+    );
+  }
+  /**
+   * Credit (add funds to) a wallet. Returns the updated wallet and ledger entries.
+   *
+   * **Requires `write` scope.**
+   */
+  async credit(walletId, request, options) {
+    return this.client._request(
+      "POST",
+      `/v1/wallets/${walletId}/credit`,
+      { body: request, idempotencyKey: options?.idempotencyKey }
+    );
+  }
+  /**
+   * Debit (remove funds from) a wallet. Returns the updated wallet and ledger entries.
+   * Throws a 402 error if the wallet has insufficient balance.
+   *
+   * **Requires `write` scope.**
+   */
+  async debit(walletId, request, options) {
+    return this.client._request(
+      "POST",
+      `/v1/wallets/${walletId}/debit`,
+      { body: request, idempotencyKey: options?.idempotencyKey }
+    );
+  }
+  /**
+   * List paginated ledger entries (transactions) for a wallet.
+   *
+   * **Requires `read` scope.**
+   */
+  async listTransactions(walletId, params) {
+    return this.client._request(
+      "GET",
+      `/v1/wallets/${walletId}/transactions`,
+      {
+        query: {
+          limit: params?.limit?.toString(),
+          offset: params?.offset?.toString()
+        }
+      }
+    );
+  }
+  /**
+   * Create a dedicated virtual bank account that automatically funds the wallet on deposit.
+   *
+   * **Requires `write` scope.**
+   */
+  async createVirtualAccount(walletId, request, options) {
+    const wrapper = await this.client._request(
+      "POST",
+      `/v1/wallets/${walletId}/virtual-accounts`,
+      { body: request, idempotencyKey: options?.idempotencyKey }
+    );
+    return wrapper.virtual_account;
+  }
+  /**
+   * List all virtual accounts linked to a wallet.
+   *
+   * **Requires `read` scope.**
+   */
+  async listVirtualAccounts(walletId) {
+    return this.client._request(
+      "GET",
+      `/v1/wallets/${walletId}/virtual-accounts`
+    );
+  }
+}
 const DEFAULT_BASE_URL = "https://api.monigo.co";
 const DEFAULT_TIMEOUT_MS = 3e4;
 class MonigoClient {
@@ -688,6 +865,8 @@ class MonigoClient {
     this.payoutAccounts = new PayoutAccountsResource(this);
     this.invoices = new InvoicesResource(this);
     this.usage = new UsageResource(this);
+    this.portalTokens = new PortalTokensResource(this);
+    this.wallets = new WalletsResource(this);
   }
   /**
    * Execute an authenticated HTTP request against the Monigo API.
@@ -801,6 +980,29 @@ const PayoutMethod = {
   BankTransfer: "bank_transfer",
   MobileMoney: "mobile_money"
 };
+const WalletEntryType = {
+  /** Credit from an external funding source. */
+  Deposit: "deposit",
+  /** Debit to an external destination. */
+  Withdrawal: "withdrawal",
+  /** Automatic debit for metered usage charges. */
+  Usage: "usage",
+  /** Credit reversing a previous charge. */
+  Refund: "refund",
+  /** Manual balance correction. */
+  Adjustment: "adjustment"
+};
+const WalletDirection = {
+  /** Reduces the wallet balance. */
+  Debit: "debit",
+  /** Increases the wallet balance. */
+  Credit: "credit"
+};
+const VirtualAccountProvider = {
+  Paystack: "paystack",
+  Flutterwave: "flutterwave",
+  Monnify: "monnify"
+};
 exports.Aggregation = Aggregation;
 exports.BillingPeriod = BillingPeriod;
 exports.CustomersResource = CustomersResource;
@@ -814,8 +1016,13 @@ exports.PayoutAccountsResource = PayoutAccountsResource;
 exports.PayoutMethod = PayoutMethod;
 exports.PlanType = PlanType;
 exports.PlansResource = PlansResource;
+exports.PortalTokensResource = PortalTokensResource;
 exports.PricingModel = PricingModel;
 exports.SubscriptionStatus = SubscriptionStatus;
 exports.SubscriptionsResource = SubscriptionsResource;
 exports.UsageResource = UsageResource;
+exports.VirtualAccountProvider = VirtualAccountProvider;
+exports.WalletDirection = WalletDirection;
+exports.WalletEntryType = WalletEntryType;
+exports.WalletsResource = WalletsResource;
 //# sourceMappingURL=monigo.cjs.map