@plyaz/types 1.16.4 → 1.16.5

package/dist/payments/gateways/provider/index.d.ts

@@ -1 +1,2 @@
 export type * from './types';
+export * from './plans';

package/dist/payments/gateways/provider/plans/enums.d.ts

@@ -0,0 +1,5 @@
+export declare enum PROVIDER_PRODUCT_STATUS {
+    Active = "active",
+    Inactive = "inactive",
+    Archived = "archived"
+}

package/dist/payments/gateways/provider/plans/index.d.ts

@@ -0,0 +1,2 @@
+export * from './enums';
+export type * from './types';

package/dist/payments/gateways/provider/plans/types.d.ts

@@ -0,0 +1,180 @@
+import type { CurrencyCode } from '../../../../locale/types';
+import type { PAYMENT_PROVIDER_TYPE } from '../../../provider';
+import type { PROVIDER_PRODUCT_STATUS } from './enums';
+/**
+ * Billing cycle for subscription or recurring payments
+ */
+export type BillingCycle = 'monthly' | 'weekly' | 'yearly' | 'daily' | 'one time' | 'period' | string;
+/**
+ * Parameters to create a new product in the payment provider
+ */
+export interface CreateProductParams<T extends object = object> {
+    /** ID of the internal plan this product is linked to */
+    planId: string;
+    /** Optional array of feature IDs associated with the plan */
+    featureIds?: string[];
+    /** Display name of the product */
+    name: string;
+    /** Optional detailed description of the product */
+    description?: string;
+    /** Payment provider (Stripe, PayPal, etc.) */
+    provider: PAYMENT_PROVIDER_TYPE;
+    /** Optional metadata for additional product info */
+    metadata?: T;
+}
+/**
+ * Result returned after successfully creating a product in the provider
+ */
+export interface CreateProductResult<T extends object = object> {
+    /** Provider-specific product ID */
+    providerProductId: string;
+    /** Provider-specific price ID, if applicable */
+    providerPriceId?: string;
+    /** Current status of the product in the provider system */
+    status: PROVIDER_PRODUCT_STATUS;
+    /** Optional metadata returned from provider */
+    metadata?: T;
+}
+/**
+ * Parameters to update an existing product in the payment provider
+ */
+export interface UpdateProductParams<T extends object = object> {
+    /** Payment provider (Stripe, PayPal, etc.) */
+    provider: PAYMENT_PROVIDER_TYPE;
+    /** Provider-specific product ID to update */
+    providerProductId: string;
+    /** Optional new display name */
+    name?: string;
+    /** Optional updated description */
+    description?: string;
+    /** Optional metadata updates */
+    metadata?: T;
+}
+/**
+ * Result returned after updating a product in the provider
+ */
+export interface UpdateProductResult<T extends object = object> {
+    /** Provider-specific product ID */
+    providerProductId: string;
+    /** Current status of the product in the provider system */
+    status: PROVIDER_PRODUCT_STATUS;
+    /** Optional metadata returned from provider */
+    metadata?: T;
+}
+/**
+ * Parameters to fetch details of a product from the provider
+ */
+export interface FetchProductParams {
+    /** Payment provider (Stripe, PayPal, etc.) */
+    provider: PAYMENT_PROVIDER_TYPE;
+    /** Provider-specific product ID to fetch */
+    providerProductId: string;
+}
+/**
+ * Result returned when fetching a product from the provider
+ */
+export interface FetchProductResult<T extends object = object> {
+    /** Provider-specific product ID */
+    providerProductId: string;
+    /** Display name of the product */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Optional price in smallest currency unit */
+    price?: number;
+    /** Optional currency code */
+    currency?: CurrencyCode;
+    /** Current status of the product in the provider system */
+    status: PROVIDER_PRODUCT_STATUS;
+    /** Optional metadata returned from provider */
+    metadata?: T;
+}
+/**
+ * Parameters to deactivate or archive a product in the provider
+ */
+export interface DeactivateProductParams {
+    /** Payment provider (Stripe, PayPal, etc.) */
+    provider: PAYMENT_PROVIDER_TYPE;
+    /** Provider-specific product ID to deactivate */
+    providerProductId: string;
+    /** Optional reason for deactivation */
+    reason?: string;
+}
+/**
+ * Parameters to create pricing for a product in the provider
+ */
+export interface CreatePricingParams<T extends object = object> {
+    /** Payment provider (Stripe, PayPal, etc.) */
+    provider: PAYMENT_PROVIDER_TYPE;
+    /** Provider-specific product ID */
+    providerProductId: string;
+    /** Amount in the smallest currency unit (e.g., cents) */
+    amount: number;
+    /** Currency code (ISO) */
+    currency: CurrencyCode;
+    /** Billing cycle for the product */
+    billingCycle: BillingCycle;
+    /** Optional number of trial days */
+    trialDays?: number;
+    /** Optional metadata for pricing */
+    metadata?: T;
+}
+/**
+ * Result returned after creating pricing in the provider
+ */
+export interface CreatePricingResult<T extends object = object> {
+    /** Provider-specific product ID */
+    providerProductId: string;
+    /** Provider-specific price ID */
+    providerPriceId: string;
+    /** Amount in the smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: CurrencyCode;
+    /** Billing cycle for the product */
+    billingCycle: BillingCycle;
+    /** Optional trial days */
+    trialDays?: number;
+    /** Status of the price in the provider system */
+    status: PROVIDER_PRODUCT_STATUS;
+    /** Optional metadata returned from provider */
+    metadata?: T;
+}
+/**
+ * Parameters to update existing pricing info in the provider
+ */
+export interface UpdatePricingParams<T extends object = object> {
+    /** Payment provider (Stripe, PayPal, etc.) */
+    provider: PAYMENT_PROVIDER_TYPE;
+    /** Provider-specific price ID to update */
+    providerPriceId: string;
+    /** Optional updated amount in smallest currency unit */
+    amount?: number;
+    /** Optional updated currency */
+    currency?: CurrencyCode;
+    /** Optional updated billing cycle */
+    billingCycle?: BillingCycle;
+    /** Optional updated trial days */
+    trialDays?: number;
+    /** Optional metadata updates */
+    metadata?: T;
+}
+/**
+ * Result returned after updating pricing in the provider
+ */
+export interface UpdatePricingResult<T extends object = object> {
+    /** Provider-specific price ID */
+    providerPriceId: string;
+    /** Updated amount in smallest currency unit */
+    amount: number;
+    /** Updated currency code */
+    currency: CurrencyCode;
+    /** Updated billing cycle */
+    billingCycle: BillingCycle;
+    /** Updated trial days, if any */
+    trialDays?: number;
+    /** Status of the price in the provider system */
+    status: PROVIDER_PRODUCT_STATUS;
+    /** Optional metadata returned from provider */
+    metadata?: T;
+}

package/dist/payments/provider/adapter/types.d.ts

@@ -1,9 +1,9 @@
 import type { CurrencyCode } from '../../../locale/types';
 import type { ProviderHealthStatus } from '../../../features';
-import type { BaseProviderConfig } from '../../gateways';
+import type { BaseProviderConfig, CreatePricingParams, CreatePricingResult, CreateProductParams, CreateProductResult, DeactivateProductParams, FetchProductParams, FetchProductResult, UpdatePricingParams, UpdatePricingResult, UpdateProductParams, UpdateProductResult } from '../../gateways';
 import type { PaymentResult, ProcessPaymentRequest } from '../../request';
 import type { FeeBreakdown, Money } from '../../transaction';
-import type { AdapterConfiguration, CreateCustomerParams, CreateSubscriptionParams, CustomerResult, FeeCalculationOptions, FeeStructure, PaymentStatusResult, PayoutParams, PayoutResult, RefundParams, RefundResult, SavedPaymentMethod, SavedPaymentMethodResult, SavePaymentMethodParams, SubscriptionResult, TransactionDetails, TransactionHistory, TransactionHistoryParams, WebhookPayload, WebhookResult } from '../core';
+import type { AdapterConfiguration, CreateCustomerParams, CreateSubscriptionParams, CustomerResult, FeeCalculationOptions, FeeStructure, PaymentStatusResult, PayoutParams, PayoutResult, RefundParams, RefundResult, SavedPaymentMethod, SavedPaymentMethodResult, SavePaymentMethodParams, SubscriptionResult, TransactionDetails, TransactionHistory, TransactionHistoryParams, WebhookPayload, WebhookResult, WithdrawalParams, WithdrawalResult } from '../core';
 import type { ProviderCapabilities, ProviderConfiguration } from '../payment-provider';
 import type { PAYMENT_METHOD, PAYMENT_PROVIDER_TYPE } from '../provider-capability';
 /**
@@ -201,9 +201,27 @@ export interface PaymentAdapter {
      * Process payout to recipient (optional)
      */
     processPayout?(params: PayoutParams): Promise<PayoutResult>;
+    /**
+     * Process withdrawal from a user's balance (optional)
+     * This method represents a user-initiated request to move funds from their platform account
+     * to an external destination, which the provider then processes as a payout.
+     * * @param params - Withdrawal request parameters
+     * @returns Withdrawal result with status
+     */
+    processWithdrawal?(params: WithdrawalParams): Promise<WithdrawalResult>;
     /**
      * Get transaction history from provider (optional).
      * Only implement if provider supports historical transaction queries.
      */
     getTransactionHistory?(params: TransactionHistoryParams): Promise<TransactionHistory>;
+    /** Create product + pricing in provider */
+    createProduct?(params: CreateProductParams): Promise<CreateProductResult>;
+    /** Update product or price info in provider */
+    updateProduct?(params: UpdateProductParams): Promise<UpdateProductResult>;
+    /** Fetch provider product details */
+    fetchProduct?(params: FetchProductParams): Promise<FetchProductResult>;
+    /** Deactivate or archive provider product */
+    deactivateProduct?(params: DeactivateProductParams): Promise<boolean>;
+    createPricing?(params: CreatePricingParams): Promise<CreatePricingResult>;
+    updatePricing?(params: UpdatePricingParams): Promise<UpdatePricingResult>;
 }

package/dist/payments/provider/core/enums.d.ts

@@ -0,0 +1,8 @@
+export declare enum WITHDRAWAL_STATUS {
+    Requested = "requested",
+    Approved = "approved",
+    InTransit = "in_transit",
+    Completed = "completed",
+    Failed = "failed",
+    Cancelled = "cancelled"
+}

package/dist/payments/provider/core/index.d.ts

@@ -1 +1,2 @@
 export type * from './types';
+export * from './enums';

package/dist/payments/provider/core/types.d.ts

@@ -1,6 +1,7 @@
 import type { CurrencyCode } from '../../../locale/types';
 import type { FeeBreakdown, Money } from '../../transaction';
 import type { PAYMENT_METHOD, PAYMENT_PROVIDER_TYPE, PAYMENT_STATUS } from '../provider-capability';
+import type { WITHDRAWAL_STATUS } from './enums';
 /**
  * Parameters required to initiate a refund.
  * Refunds can be full or partial.
@@ -350,31 +351,29 @@ export interface SavedPaymentMethod<TMetadata extends object = object> {
     metadata?: TMetadata;
 }
 export interface CreateSubscriptionParams<TMetadata extends object = object> {
-    /** Plyaz user ID */
+    /** Plyaz user ID (Stripe customer ID or your internal user ID mapped to Stripe) */
     userId: string;
-    /** Amount per billing cycle */
-    amount: Money;
-    /** Billing cycle (in ISO 8601 duration or custom format) */
-    billingCycle: string;
-    /** Payment method to charge */
+    /** Plan to subscribe the user to: 'standard' | 'pro' | 'enterprise' */
+    plan: 'standard' | 'pro' | 'enterprise';
+    /** Payment method to charge (Stripe payment method ID) */
     paymentMethodId: string;
     /** Optional trial period in days */
     trialDays?: number;
-    /** Subscription metadata */
+    /** Optional metadata for additional info */
     metadata?: TMetadata;
 }
 export interface SubscriptionResult<TMetadata extends object = object> {
-    /** Internal Plyaz subscription ID */
+    /** Internal subscription ID */
     subscriptionId: string;
     /** Provider subscription ID */
     providerSubscriptionId?: string;
-    /** Current subscription status */
+    /** Status: active, trialing, paused, canceled, expired */
     status: 'active' | 'trialing' | 'paused' | 'canceled' | 'expired';
     /** Next billing date */
     nextBillingDate?: Date;
-    /** Start date of subscription */
+    /** Subscription start date */
     startedAt: Date;
-    /** Metadata and provider payload */
+    /** Provider-specific metadata */
     metadata?: TMetadata;
 }
 export interface PayoutParams<TMetadata extends object = object> {
@@ -425,3 +424,50 @@ export interface ReceiptData<TMetadata extends object = object> {
     total: Money;
     providerMetadata?: TMetadata;
 }
+/**
+ * Parameters required for a user-initiated withdrawal request.
+ * Represents a user requesting to move funds from their platform balance to an external account.
+ */
+export interface WithdrawalParams<TMetadata extends object = object> {
+    /** Unique ID of the user requesting the withdrawal */
+    userId: string;
+    /** Amount to withdraw */
+    amount: Money;
+    /** CurrencyCode of the withdrawal */
+    CurrencyCode: CurrencyCode;
+    /**
+     * Optional ID of the saved external account (bank, card) to send funds to.
+     * This is analogous to `destinationId` in Payouts, but tied to a user's saved method.
+     */
+    destinationAccountId?: string;
+    /** Reason or description for the withdrawal (e.g., 'Cashing out earnings') */
+    reason?: string;
+    /** Optional idempotency key to prevent duplicate requests */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: TMetadata;
+}
+/**
+ * Result returned after processing a withdrawal request.
+ * The status tracks the disbursement process back to the user's account.
+ */
+export interface WithdrawalResult<TMetadata extends object = object> {
+    /** Internal Plyaz withdrawal ID */
+    withdrawalId: string;
+    /** Provider-specific transaction ID (often the underlying Payout ID) */
+    providerTransactionId?: string;
+    /** Current status of the withdrawal */
+    status: WITHDRAWAL_STATUS;
+    /** Final amount successfully transferred */
+    amount: Money;
+    /** Any fees deducted from the withdrawal amount */
+    fees?: FeeBreakdown;
+    /** Timestamp when the withdrawal request was submitted */
+    requestedAt: Date;
+    /** Estimated or actual completion time */
+    completedAt?: Date;
+    /** Failure reason message, if status is 'failed' */
+    failureReason?: string;
+    /** Metadata and provider response */
+    metadata?: TMetadata;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.16.4",
+  "version": "1.16.5",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",