@moonpay/platform-sdk-core 0.0.0 → 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,167 @@
+import * as _moonpay_platform_protocol from '@moonpay/platform-protocol';
+import { Result, DevPlatformApiError, GetQuoteParams, GetQuoteError, TransactionWithStages, GetTransactionsError, Transaction, PaginationInfo, ListPaymentMethodsResponse, GetPaymentMethodsError, ProtocolMessage, Quote, DecryptedCredentials } from '@moonpay/platform-protocol';
+
+/** Internal state container for authenticated API access. */
+interface ClientContext {
+    readonly accessToken: string;
+    readonly clientToken: string;
+    setAccessToken(token: string): void;
+    setClientToken(token: string): void;
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+interface ClientContextOptions {
+    /** Base URL for the MoonPay Platform API. Defaults to production. */
+    apiBaseUrl?: string;
+}
+declare function createClientContext(options?: ClientContextOptions): ClientContext;
+
+/** Typed fetch that wraps responses in Result<T, E>. */
+declare function apiFetch<T>(ctx: ClientContext, path: string, options?: RequestInit): Promise<Result<T, DevPlatformApiError>>;
+
+/** The API wraps the quote in a `{ data: ... }` envelope. */
+interface GetQuoteApiResponse {
+    data: _moonpay_platform_protocol.Quote;
+}
+declare function getQuote(ctx: ClientContext, params: GetQuoteParams): Promise<Result<GetQuoteApiResponse, GetQuoteError>>;
+
+interface ListTransactionsParams {
+    startDate?: string;
+    endDate?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface ListTransactionsApiResponse {
+    data: Transaction[];
+    pageInfo: PaginationInfo;
+}
+declare function listTransactions(ctx: ClientContext, params?: ListTransactionsParams): Promise<Result<ListTransactionsApiResponse, GetTransactionsError>>;
+interface GetTransactionApiResponse {
+    data: TransactionWithStages;
+}
+declare function getTransaction(ctx: ClientContext, id: string): Promise<Result<GetTransactionApiResponse, GetTransactionsError>>;
+
+declare function getPaymentMethods(ctx: ClientContext): Promise<Result<ListPaymentMethodsResponse, GetPaymentMethodsError>>;
+declare function deletePaymentMethod(ctx: ClientContext, paymentMethodId: string): Promise<Result<void, DevPlatformApiError>>;
+
+/** Options for creating a frame (iframe or WebView). */
+interface FrameOptions {
+    /** Container to render the frame into. Platform-specific. */
+    container: unknown;
+    /** Whether this is a hidden utility frame (e.g., check-connection). */
+    hidden?: boolean;
+}
+/**
+ * Platform-agnostic transport interface for frame communication.
+ * Implemented by `IframeTransport` (web) and `WebViewTransport` (RN).
+ */
+interface FrameTransport {
+    /** Create and mount the frame with the given URL. */
+    create(url: string, options: FrameOptions): void;
+    /** Send a protocol message to the frame. */
+    sendMessage(message: ProtocolMessage): void;
+    /**
+     * Register a handler for incoming protocol messages.
+     * Returns an unsubscribe function.
+     */
+    onMessage(handler: (message: ProtocolMessage) => void): () => void;
+    /** Remove the frame and clean up all listeners. */
+    dispose(): void;
+}
+
+declare const FRAME_PATHS: {
+    readonly connect: "/platform/v1/connect";
+    readonly checkConnection: "/platform/v1/check-connection";
+    readonly applePay: "/platform/v1/apple-pay";
+    readonly googlePay: "/platform/v1/google-pay";
+    readonly widget: "/platform/v1/widget";
+    readonly buy: "/platform/v1/buy";
+    readonly buyButton: "/platform/v1/buy-button";
+    readonly challenge: "/platform/v1/challenge";
+    readonly addCard: "/platform/v1/add-card";
+    readonly reset: "/platform/v1/reset";
+};
+interface UrlBuilderOptions {
+    /** Base URL for MoonPay frames. Defaults to production. */
+    frameBaseUrl?: string;
+}
+/** Build a frame URL with query parameters. */
+declare function buildFrameUrl(path: string, query?: Record<string, unknown>, options?: UrlBuilderOptions): string;
+
+interface CoreClientOptions extends ClientContextOptions, UrlBuilderOptions {
+    /**
+     * Factory to create a platform-specific FrameTransport.
+     * Provided by the web or react-native SDK.
+     */
+    createTransport: () => FrameTransport;
+}
+interface CoreClient {
+    /** Access the internal context (for platform SDKs). */
+    readonly context: ClientContext;
+    /** Frame base URL option (for platform SDKs building frame URLs). */
+    readonly frameBaseUrl: string | undefined;
+    /** Factory to create transports (for platform SDKs). */
+    createTransport(): FrameTransport;
+    getQuote(params: GetQuoteParams): Promise<Result<{
+        data: Quote;
+    }, GetQuoteError>>;
+    getPaymentMethods(): Promise<Result<ListPaymentMethodsResponse, GetPaymentMethodsError>>;
+    listTransactions(params?: ListTransactionsParams): Promise<Result<{
+        data: Transaction[];
+        pageInfo: PaginationInfo;
+    }, GetTransactionsError>>;
+    getTransaction(id: string): Promise<Result<{
+        data: TransactionWithStages;
+    }, GetTransactionsError>>;
+    deletePaymentMethod(id: string): Promise<Result<void, DevPlatformApiError>>;
+}
+/**
+ * Creates the platform-agnostic core client.
+ * Platform SDKs (web, react-native) wrap this with frame-specific logic.
+ */
+declare function createClientCore(options: CoreClientOptions): CoreClient;
+
+/**
+ * Decrypt credentials received from the connect/check-connection frame.
+ *
+ * The frame encrypts credentials using X25519 ECDH + HKDF + AES-GCM.
+ * The SDK generated an ephemeral key pair and sent the public key to the frame
+ * via query parameters. The frame encrypted using that public key; we decrypt
+ * using our private key.
+ */
+declare function decryptCredentials(encryptedPayload: string, privateKeyHex: string): DecryptedCredentials;
+
+interface KeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+/** Generate an ephemeral X25519 key pair for the encrypted credential exchange. */
+declare function generateKeyPair(): KeyPair;
+
+interface FrameOrchestratorOptions {
+    transport: FrameTransport;
+    channelId: string;
+    url: string;
+    container: unknown;
+    hidden?: boolean;
+    /** Timeout in ms for the handshake. Defaults to 15000. */
+    handshakeTimeout?: number;
+}
+interface FrameHandle {
+    /** Send a typed message to the frame. */
+    sendMessage(message: ProtocolMessage): void;
+    /** Register a message handler. Returns unsubscribe function. */
+    onMessage(handler: (message: ProtocolMessage) => void): () => void;
+    /** Tear down the frame and all listeners. */
+    dispose(): void;
+}
+/**
+ * Orchestrates the handshake and message routing between the SDK and a frame.
+ *
+ * 1. Creates the frame via the transport
+ * 2. Waits for the `handshake` message from the frame
+ * 3. Responds with `ack`
+ * 4. Returns a handle for sending/receiving typed messages
+ */
+declare function createFrameOrchestrator(options: FrameOrchestratorOptions): Promise<FrameHandle>;
+
+export { type ClientContext, type ClientContextOptions, type CoreClient, type CoreClientOptions, FRAME_PATHS, type FrameHandle, type FrameOptions, type FrameOrchestratorOptions, type FrameTransport, type KeyPair, type ListTransactionsParams, type UrlBuilderOptions, apiFetch, buildFrameUrl, createClientContext, createClientCore, createFrameOrchestrator, decryptCredentials, deletePaymentMethod, generateKeyPair, getPaymentMethods, getQuote, getTransaction, listTransactions };

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import * as _moonpay_platform_protocol from '@moonpay/platform-protocol';
+import { Result, DevPlatformApiError, GetQuoteParams, GetQuoteError, TransactionWithStages, GetTransactionsError, Transaction, PaginationInfo, ListPaymentMethodsResponse, GetPaymentMethodsError, ProtocolMessage, Quote, DecryptedCredentials } from '@moonpay/platform-protocol';
+
+/** Internal state container for authenticated API access. */
+interface ClientContext {
+    readonly accessToken: string;
+    readonly clientToken: string;
+    setAccessToken(token: string): void;
+    setClientToken(token: string): void;
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+interface ClientContextOptions {
+    /** Base URL for the MoonPay Platform API. Defaults to production. */
+    apiBaseUrl?: string;
+}
+declare function createClientContext(options?: ClientContextOptions): ClientContext;
+
+/** Typed fetch that wraps responses in Result<T, E>. */
+declare function apiFetch<T>(ctx: ClientContext, path: string, options?: RequestInit): Promise<Result<T, DevPlatformApiError>>;
+
+/** The API wraps the quote in a `{ data: ... }` envelope. */
+interface GetQuoteApiResponse {
+    data: _moonpay_platform_protocol.Quote;
+}
+declare function getQuote(ctx: ClientContext, params: GetQuoteParams): Promise<Result<GetQuoteApiResponse, GetQuoteError>>;
+
+interface ListTransactionsParams {
+    startDate?: string;
+    endDate?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface ListTransactionsApiResponse {
+    data: Transaction[];
+    pageInfo: PaginationInfo;
+}
+declare function listTransactions(ctx: ClientContext, params?: ListTransactionsParams): Promise<Result<ListTransactionsApiResponse, GetTransactionsError>>;
+interface GetTransactionApiResponse {
+    data: TransactionWithStages;
+}
+declare function getTransaction(ctx: ClientContext, id: string): Promise<Result<GetTransactionApiResponse, GetTransactionsError>>;
+
+declare function getPaymentMethods(ctx: ClientContext): Promise<Result<ListPaymentMethodsResponse, GetPaymentMethodsError>>;
+declare function deletePaymentMethod(ctx: ClientContext, paymentMethodId: string): Promise<Result<void, DevPlatformApiError>>;
+
+/** Options for creating a frame (iframe or WebView). */
+interface FrameOptions {
+    /** Container to render the frame into. Platform-specific. */
+    container: unknown;
+    /** Whether this is a hidden utility frame (e.g., check-connection). */
+    hidden?: boolean;
+}
+/**
+ * Platform-agnostic transport interface for frame communication.
+ * Implemented by `IframeTransport` (web) and `WebViewTransport` (RN).
+ */
+interface FrameTransport {
+    /** Create and mount the frame with the given URL. */
+    create(url: string, options: FrameOptions): void;
+    /** Send a protocol message to the frame. */
+    sendMessage(message: ProtocolMessage): void;
+    /**
+     * Register a handler for incoming protocol messages.
+     * Returns an unsubscribe function.
+     */
+    onMessage(handler: (message: ProtocolMessage) => void): () => void;
+    /** Remove the frame and clean up all listeners. */
+    dispose(): void;
+}
+
+declare const FRAME_PATHS: {
+    readonly connect: "/platform/v1/connect";
+    readonly checkConnection: "/platform/v1/check-connection";
+    readonly applePay: "/platform/v1/apple-pay";
+    readonly googlePay: "/platform/v1/google-pay";
+    readonly widget: "/platform/v1/widget";
+    readonly buy: "/platform/v1/buy";
+    readonly buyButton: "/platform/v1/buy-button";
+    readonly challenge: "/platform/v1/challenge";
+    readonly addCard: "/platform/v1/add-card";
+    readonly reset: "/platform/v1/reset";
+};
+interface UrlBuilderOptions {
+    /** Base URL for MoonPay frames. Defaults to production. */
+    frameBaseUrl?: string;
+}
+/** Build a frame URL with query parameters. */
+declare function buildFrameUrl(path: string, query?: Record<string, unknown>, options?: UrlBuilderOptions): string;
+
+interface CoreClientOptions extends ClientContextOptions, UrlBuilderOptions {
+    /**
+     * Factory to create a platform-specific FrameTransport.
+     * Provided by the web or react-native SDK.
+     */
+    createTransport: () => FrameTransport;
+}
+interface CoreClient {
+    /** Access the internal context (for platform SDKs). */
+    readonly context: ClientContext;
+    /** Frame base URL option (for platform SDKs building frame URLs). */
+    readonly frameBaseUrl: string | undefined;
+    /** Factory to create transports (for platform SDKs). */
+    createTransport(): FrameTransport;
+    getQuote(params: GetQuoteParams): Promise<Result<{
+        data: Quote;
+    }, GetQuoteError>>;
+    getPaymentMethods(): Promise<Result<ListPaymentMethodsResponse, GetPaymentMethodsError>>;
+    listTransactions(params?: ListTransactionsParams): Promise<Result<{
+        data: Transaction[];
+        pageInfo: PaginationInfo;
+    }, GetTransactionsError>>;
+    getTransaction(id: string): Promise<Result<{
+        data: TransactionWithStages;
+    }, GetTransactionsError>>;
+    deletePaymentMethod(id: string): Promise<Result<void, DevPlatformApiError>>;
+}
+/**
+ * Creates the platform-agnostic core client.
+ * Platform SDKs (web, react-native) wrap this with frame-specific logic.
+ */
+declare function createClientCore(options: CoreClientOptions): CoreClient;
+
+/**
+ * Decrypt credentials received from the connect/check-connection frame.
+ *
+ * The frame encrypts credentials using X25519 ECDH + HKDF + AES-GCM.
+ * The SDK generated an ephemeral key pair and sent the public key to the frame
+ * via query parameters. The frame encrypted using that public key; we decrypt
+ * using our private key.
+ */
+declare function decryptCredentials(encryptedPayload: string, privateKeyHex: string): DecryptedCredentials;
+
+interface KeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+/** Generate an ephemeral X25519 key pair for the encrypted credential exchange. */
+declare function generateKeyPair(): KeyPair;
+
+interface FrameOrchestratorOptions {
+    transport: FrameTransport;
+    channelId: string;
+    url: string;
+    container: unknown;
+    hidden?: boolean;
+    /** Timeout in ms for the handshake. Defaults to 15000. */
+    handshakeTimeout?: number;
+}
+interface FrameHandle {
+    /** Send a typed message to the frame. */
+    sendMessage(message: ProtocolMessage): void;
+    /** Register a message handler. Returns unsubscribe function. */
+    onMessage(handler: (message: ProtocolMessage) => void): () => void;
+    /** Tear down the frame and all listeners. */
+    dispose(): void;
+}
+/**
+ * Orchestrates the handshake and message routing between the SDK and a frame.
+ *
+ * 1. Creates the frame via the transport
+ * 2. Waits for the `handshake` message from the frame
+ * 3. Responds with `ack`
+ * 4. Returns a handle for sending/receiving typed messages
+ */
+declare function createFrameOrchestrator(options: FrameOrchestratorOptions): Promise<FrameHandle>;
+
+export { type ClientContext, type ClientContextOptions, type CoreClient, type CoreClientOptions, FRAME_PATHS, type FrameHandle, type FrameOptions, type FrameOrchestratorOptions, type FrameTransport, type KeyPair, type ListTransactionsParams, type UrlBuilderOptions, apiFetch, buildFrameUrl, createClientContext, createClientCore, createFrameOrchestrator, decryptCredentials, deletePaymentMethod, generateKeyPair, getPaymentMethods, getQuote, getTransaction, listTransactions };