@beep-it/sdk-core 0.1.1 → 0.1.2-beta.2

package/dist/types/payment.d.ts

@@ -19,6 +19,14 @@ export interface RequestAndPurchaseAssetRequestParams {
     /** Label to display on the payment request (e.g., merchant name) */
     paymentLabel?: string;
 }
+/**
+ * 402 Flow semantics:
+ * - Phase 1 (no paymentReference): server responds with HTTP 402 Payment Required and a payload
+ *   containing referenceKey/paymentUrl/qrCode. The SDK returns that payload so callers can show
+ *   a QR or deep link to the user.
+ * - Phase 2 (with paymentReference): call again. When payment is complete, the response will NOT
+ *   include referenceKey. If referenceKey is still present (or a 402 payload is returned), keep polling.
+ */
 /**
  * Payload for creating a payment request
  * This interface represents the data needed to initiate a payment flow
@@ -105,4 +113,207 @@ export interface SignSolanaTransactionData {
     /** Current status of the associated invoice */
     status: InvoiceStatus;
 }
+/**
+ * Payload for issuing a payment request that creates a streaming payment session
+ *
+ * This interface is used for server-to-server payment issuance where one merchant
+ * (the paying party) creates a payment request for assets to be charged over time.
+ *
+ * **Important**: This functionality is only available with `BeepClient` using secret API keys.
+ * It is NOT supported with `BeepPublicClient` or publishable keys for security reasons.
+ *
+ * @example
+ * ```typescript
+ * // Only works with BeepClient (server-side)
+ * const beep = new BeepClient({ apiKey: 'secret_key_here' });
+ *
+ * const paymentRequest = await beep.payments.issuePayment({
+ *   apiKey: 'secret_api_key',
+ *   assetChunks: [
+ *     { assetId: 'video-content-uuid', quantity: 1 },
+ *     { assetId: 'api-access-uuid', quantity: 10 }
+ *   ],
+ *   payingMerchantId: 'merchant_abc123',
+ *   invoiceId: 'existing_invoice_uuid' // optional
+ * });
+ * ```
+ */
+export interface IssuePaymentPayload {
+    /**
+     * Secret API key for authentication
+     * @remarks Must be a secret key, not a publishable key
+     */
+    apiKey: string;
+    /**
+     * Array of asset chunks to be purchased in this payment request
+     * @remarks Each asset will be charged according to its configured pricing
+     */
+    assetChunks: BeepPurchaseAsset[];
+    /**
+     * ID of the merchant who will be charged for these assets
+     * @remarks This is the paying party, not the receiving party
+     */
+    payingMerchantId: string;
+    /**
+     * Optional existing invoice ID to associate with this payment
+     * @remarks If provided, assets will be added to the existing invoice
+     */
+    invoiceId?: string;
+}
+/**
+ * Response returned after successfully issuing a payment
+ *
+ * Contains the identifiers needed to track and manage the streaming payment session.
+ * The reference key can be used for status polling, and the invoice ID for payment management.
+ */
+export interface IssuePaymentResponse {
+    /**
+     * Unique reference key for tracking this streaming payment session
+     * @remarks Use this key to poll payment status and manage the session
+     */
+    referenceKey: string;
+    /**
+     * UUID of the invoice created for this streaming payment
+     * @remarks Use this ID for starting, pausing, or stopping the streaming session
+     */
+    invoiceId: string;
+}
+/**
+ * Payload for starting a streaming payment session
+ *
+ * Initiates billing for a previously issued payment request. Once started,
+ * the merchant will begin being charged for asset usage according to the
+ * streaming payment configuration.
+ *
+ * **Important**: This functionality is only available with `BeepClient` using secret API keys.
+ * It is NOT supported with `BeepPublicClient` or publishable keys.
+ *
+ * @example
+ * ```typescript
+ * // Start charging for the streaming session
+ * const result = await beep.payments.startStreaming({
+ *   apiKey: 'secret_api_key',
+ *   invoiceId: 'invoice_uuid_from_issuePayment'
+ * });
+ * ```
+ */
+export interface StartStreamingPayload {
+    /**
+     * Secret API key for authentication
+     * @remarks Must be a secret key, not a publishable key
+     */
+    apiKey: string;
+    /**
+     * UUID of the invoice to start streaming charges for
+     * @remarks This should be the invoiceId returned from issuePayment()
+     */
+    invoiceId: string;
+}
+/**
+ * Response returned after successfully starting a streaming payment session
+ *
+ * Confirms that the streaming session has been activated and charging has begun.
+ */
+export interface StartStreamingResponse {
+    /**
+     * The UUID of the streaming invoice that was started
+     * @remarks Matches the invoiceId from the request for confirmation
+     */
+    invoiceId: string;
+}
+/**
+ * Payload for pausing an active streaming payment session
+ *
+ * Temporarily halts billing for a streaming session without terminating it.
+ * The session can be resumed later using startStreaming() with the same invoice ID.
+ *
+ * **Important**: This functionality is only available with `BeepClient` using secret API keys.
+ * It is NOT supported with `BeepPublicClient` or publishable keys.
+ *
+ * @example
+ * ```typescript
+ * // Temporarily pause billing
+ * const result = await beep.payments.pauseStreaming({
+ *   apiKey: 'secret_api_key',
+ *   invoiceId: 'active_invoice_uuid'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Streaming paused successfully');
+ * }
+ * ```
+ */
+export interface PauseStreamingPayload {
+    /**
+     * Secret API key for authentication
+     * @remarks Must be a secret key, not a publishable key
+     */
+    apiKey: string;
+    /**
+     * UUID of the invoice to pause streaming for
+     * @remarks Invoice must be in an active streaming state
+     */
+    invoiceId: string;
+}
+/**
+ * Response returned after attempting to pause a streaming payment session
+ *
+ * Indicates whether the pause operation was successful.
+ */
+export interface PauseStreamingResponse {
+    /**
+     * Whether the streaming session was successfully paused
+     * @remarks If false, check that the invoice is in a valid state for pausing
+     */
+    success: boolean;
+}
+/**
+ * Payload for permanently stopping a streaming payment session
+ *
+ * Terminates a streaming session and finalizes all charges. This action cannot
+ * be undone - the session cannot be restarted after stopping.
+ *
+ * **Important**: This functionality is only available with `BeepClient` using secret API keys.
+ * It is NOT supported with `BeepPublicClient` or publishable keys.
+ *
+ * @example
+ * ```typescript
+ * // Permanently stop and finalize the streaming session
+ * const result = await beep.payments.stopStreaming({
+ *   apiKey: 'secret_api_key',
+ *   invoiceId: 'active_invoice_uuid'
+ * });
+ *
+ * console.log('Session stopped, reference keys:', result.referenceKeys);
+ * ```
+ */
+export interface StopStreamingPayload {
+    /**
+     * Secret API key for authentication
+     * @remarks Must be a secret key, not a publishable key
+     */
+    apiKey: string;
+    /**
+     * UUID of the invoice to permanently stop streaming for
+     * @remarks This action will finalize all charges and cannot be undone
+     */
+    invoiceId: string;
+}
+/**
+ * Response returned after successfully stopping a streaming payment session
+ *
+ * Contains the final session details and all associated reference keys for record keeping.
+ */
+export interface StopStreamingResponse {
+    /**
+     * The UUID of the invoice that was stopped
+     * @remarks Matches the invoiceId from the request for confirmation
+     */
+    invoiceId: string;
+    /**
+     * List of all reference keys associated with the streaming payments in this session
+     * @remarks Useful for reconciliation and record keeping of all charges made
+     */
+    referenceKeys: string[];
+}
 //# sourceMappingURL=payment.d.ts.map

package/dist/types/payment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../src/types/payment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AAEH,MAAM,WAAW,oCAAoC;IACnD,8DAA8D;IAC9D,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,SAAS,EAAE,IAAI,CAAC;IAChB,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,EAAE,aAAa,CAAC;CACvB"}
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../src/types/payment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AAEH,MAAM,WAAW,oCAAoC;IACnD,8DAA8D;IAC9D,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,SAAS,EAAE,IAAI,CAAC;IAChB,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB"}

package/dist/types/public.d.ts

@@ -0,0 +1,34 @@
+import { BeepPurchaseAsset } from './payment';
+import { SupportedToken } from './token';
+import { InvoiceStatus } from './invoice';
+/**
+ * On-the-fly item sent from the browser. The server will create a corresponding product record
+ * during the payment-session so it is persisted for audit/reuse. Safe to send from clients.
+ */
+export interface EphemeralItem {
+    name: string;
+    price: string;
+    quantity?: number;
+    token?: SupportedToken;
+    description?: string;
+}
+export type PublicAssetInput = BeepPurchaseAsset | EphemeralItem;
+export interface PublicPaymentSessionRequest {
+    publishableKey: string;
+    assets: PublicAssetInput[];
+    paymentLabel?: string;
+    generateQrCode?: boolean;
+}
+export interface PublicPaymentSessionResponse {
+    referenceKey: string;
+    paymentUrl: string;
+    qrCode?: string;
+    amount: string;
+    expiresAt: string | Date;
+    status: InvoiceStatus | string;
+}
+export interface PublicPaymentStatusResponse {
+    paid: boolean;
+    status?: InvoiceStatus | string;
+}
+//# sourceMappingURL=public.d.ts.map

package/dist/types/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/types/public.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAEjE,MAAM,WAAW,2BAA2B;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beep-it/sdk-core",
-  "version": "0.1.1",
+  "version": "0.1.2-beta.2",
   "description": "Official TypeScript SDK for the BEEP Payment and Invoice Server",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",