@casual-simulation/aux-records 3.8.1 → 3.10.2

package/SubscriptionController.d.ts

@@ -1,10 +1,30 @@
 import type { AuthController, ValidateSessionKeyFailure } from './AuthController';
 import type { AuthStore } from './AuthStore';
-import type { StripeInterface } from './StripeInterface';
+import type { StripeAccount, StripeInterface } from './StripeInterface';
 import type { NotAuthorizedError, NotLoggedInError, ServerError } from '@casual-simulation/aux-common/Errors';
 import type { RecordsStore } from './RecordsStore';
+import type { StripeAccountStatus, StripeRequirementsStatus } from './StripeInterface';
 import type { ConfigurationStore } from './ConfigurationStore';
-import type { UserRole } from '@casual-simulation/aux-common';
+import type { UserRole, DenialReason, Result, SimpleError, KnownErrorCodes, AccountBalance } from '@casual-simulation/aux-common';
+import type { PurchasableItemRecordsStore } from './purchasable-items/PurchasableItemRecordsStore';
+import type { AuthorizeSubjectFailure, ConstructAuthorizationContextFailure, PolicyController } from './PolicyController';
+import type { PolicyStore } from './PolicyStore';
+import type { AccountBalances, FinancialAccount, FinancialAccountFilter, FinancialController, FinancialStore, PayoutDestination } from './financial';
+import { TransferCodes } from './financial';
+import type { ContractInvoice, ContractRecord, ContractRecordsStore, InvoicePayoutDestination } from './contracts/ContractRecordsStore';
+import type { Transfer } from 'tigerbeetle-node';
+/**
+ * The number of bytes that the access key secret should be.
+ */
+export declare const ACCESS_KEY_SECRET_BYTE_LENGTH = 16;
+/**
+ * The number of bytes that the access key ID should be.
+ */
+export declare const ACCESS_KEY_ID_BYTE_LENGTH = 16;
+/**
+ * The number of seconds to wait before a Stripe payout transfer times out.
+ */
+export declare const STRIPE_PAYOUT_TIMEOUT_SECONDS: number;
 /**
  * Defines a class that is able to handle subscriptions.
  */
@@ -14,13 +34,30 @@ export declare class SubscriptionController {
     private _authStore;
     private _recordsStore;
     private _config;
-    constructor(stripe: StripeInterface | null, auth: AuthController, authStore: AuthStore, recordsStore: RecordsStore, config: ConfigurationStore);
+    private _policies;
+    private _policyStore;
+    private _purchasableItems;
+    private _financialController;
+    private _financialStore;
+    private _contractRecords;
+    constructor(stripe: StripeInterface | null, auth: AuthController, authStore: AuthStore, recordsStore: RecordsStore, config: ConfigurationStore, policies: PolicyController, policyStore: PolicyStore, purchasableItems: PurchasableItemRecordsStore, financialController: FinancialController | null, financialStore: FinancialStore | null, contractRecords: ContractRecordsStore);
     private _getConfig;
     /**
      * Gets the status of the given user's scription.
      * @param request
      */
     getSubscriptionStatus(request: GetSubscriptionStatusRequest): Promise<GetSubscriptionStatusResult>;
+    /**
+     * Gets the account balances for the user/studio/contract.
+     * @param request
+     */
+    getBalances(request: GetBalancesRequest): Promise<Result<AccountBalances, SimpleError>>;
+    private _checkAuthorizationForFilter;
+    /**
+     * Lists the transfers for the given account.
+     * @param request The request.
+     */
+    listAccountTransfers(request: ListAccountTransfersRequest): Promise<Result<ListedAccountTransfers, SimpleError>>;
     /**
      * Attempts to update the subscription for the given user.
      * @param request The request to update the subscription.
@@ -33,12 +70,140 @@ export declare class SubscriptionController {
      * Returns a link that the user can be redirected to to initiate a purchase of the subscription.
      */
     createManageSubscriptionLink(request: CreateManageSubscriptionRequest): Promise<CreateManageSubscriptionResult>;
+    /**
+     * Creates a link that the user can be redirected to in order to manage their store account.
+     * @param request The request to create the manage store account link.
+     * @returns
+     */
+    createManageStoreAccountLink(request: CreateManageStoreAccountLinkRequest): Promise<ManageAccountLinkResult>;
+    /**
+     * Creates a link that the user can be redirected to in order to manage their stripe XP account.
+     * @param request The request to create the manage xp account link.
+     */
+    createManageXpAccountLink(request: CreateManageXpAccountLinkRequest): Promise<ManageAccountLinkResult>;
+    /**
+     * Creates a link that the user can be redirected to in order to login to their stripe account.
+     * @param request The request to create the manage xp account link.
+     */
+    createStripeLoginLink(request: CreateStripeLoginLinkRequest): Promise<ManageAccountLinkResult>;
+    /**
+     * Creates a session that can be used to display stripe embedded components for the user.
+     * @param request The request to create the account session.
+     */
+    createStripeAccountSession(request: CreateStripeLoginLinkRequest): Promise<CreateStripeAccountSessionResult>;
     private _createCheckoutSession;
+    /**
+     * Creates a link that the user can be redirected to in order to purchase a purchasable item.
+     * @param request The request to create the purchase item link.
+     */
+    createPurchaseItemLink(request: CreatePurchaseItemLinkRequest): Promise<CreatePurchaseItemLinkResult>;
+    /**
+     * Gets the details required for purchasing a contract.
+     * @param request The request.
+     */
+    private _getContractPurchaseDetails;
+    /**
+     * Gets the pricing information for a contract.
+     * @param request The request.
+     */
+    getContractPricing(request: GetContractPricingRequest): Promise<Result<ContractPricing, SimpleError>>;
+    /**
+     * Creates a link that the user can be redirected to in order to purchase a contract.
+     * @param request The request to purchase the contract.
+     * @returns A promise that resolves to the result of the purchase contract operation.
+     */
+    purchaseContract(request: PurchaseContractRequest): Promise<PurchaseContractResult>;
+    /**
+     * Cancels a contract and issues a refund if applicable.
+     * @param request The request to cancel the contract.
+     * @returns A promise that resolves to the result of the cancel contract operation.
+     */
+    cancelContract(request: CancelContractRequest): Promise<CancelContractResult>;
+    /**
+     * Issues a new invoice for a contract.
+     * @param request The request to invoice the contract.
+     */
+    invoiceContract(request: InvoiceContractRequest): Promise<Result<{
+        invoiceId: string;
+    }, SimpleError>>;
+    /**
+     * Cancels an invoice for a contract.
+     * @param request The request to cancel the invoice.
+     */
+    cancelInvoice(request: CancelInvoiceRequest): Promise<Result<void, SimpleError>>;
+    /**
+     * Lists all invoices for a contract.
+     * @param request The request to list the invoices.
+     */
+    listContractInvoices(request: ListContractInvoicesRequest): Promise<Result<ContractInvoice[], SimpleError>>;
+    /**
+     * Pays an invoice for a contract.
+     * @param request The request to pay the invoice.
+     */
+    payContractInvoice(request: PayContractInvoiceRequest): Promise<Result<void, SimpleError>>;
+    /**
+     * Attempts to payout an account.
+     * @param request The request.
+     */
+    payoutAccount(request: InternalPayoutRequest): Promise<Result<{
+        payoutId: string;
+    }, SimpleError>>;
+    private _payoutToStripe;
+    private _payoutToCash;
+    /**
+     * Initiates a refund for a canceled contract.
+     * @param request The request to cancel the contract.
+     * @param item The contract record to refund.
+     * @param context The authorization context for the operation.
+     * @returns A promise that resolves to the result of the refund operation.
+     */
+    private _refundContract;
+    /**
+     * Completes a checkout session. Grants the user access to the purchased items or completes a contract purchase.
+     * @param request The request for the checkout session fulfillment.
+     * @returns A promise that resolves to the result of the checkout session fulfillment.
+     */
+    fulfillCheckoutSession(request: FulfillCheckoutSessionRequest): Promise<FulfillCheckoutSessionResult>;
+    claimActivationKey(request: ClaimActivationKeyRequest): Promise<ClaimActivationKeyResult>;
     /**
      * Handles the webhook from Stripe for updating the internal database.
      */
     handleStripeWebhook(request: HandleStripeWebhookRequest): Promise<HandleStripeWebhookResponse>;
+    private _handleStripeCheckoutSessionEvent;
+    private _handleStripeAccountUpdatedEvent;
+    private _handleStudioStripeAccountUpdatedEvent;
+    private _handleUserStripeAccountUpdatedEvent;
+    private _handleStripeInvoicePaidEvent;
+    private _internalTransactionPurchaseCreditsStripe;
+    private _handleStripeSubscriptionEvent;
 }
+/**
+ * Gets the account status for the given stripe account.
+ * @param account The account that the status should be retrieved for.
+ */
+export declare function getAccountStatus(account: StripeAccount): StripeAccountStatus;
+/**
+ * Gets the requirements status for the given stripe account.
+ * @param account The account.
+ */
+export declare function getAccountRequirementsStatus(account: StripeAccount): StripeRequirementsStatus;
+/**
+ * Formats a V1 access key.
+ * @param itemId The ID of the purchased item.
+ * @param secret The secret that should be used to access the purchased item.
+ */
+export declare function formatV1ActivationKey(itemId: string, secret: string): string;
+/**
+ * Parses the given access key.
+ * Returns null if the access key is invalid.
+ * @param key The key to parse.
+ */
+export declare function parseActivationKey(key: string): [keyId: string, secret: string];
+/**
+ * Generates a human readable note for the given transfer.
+ * @param transfer The transfer that should be characterized.
+ */
+export declare function charactarizeTransfer(transfer: Transfer): string | null;
 /**
  * Defines a request for managing a user's subscription.
  */
@@ -125,6 +290,12 @@ export interface GetSubscriptionStatusSuccess {
      * The list of subscriptions that the user can purchase.
      */
     purchasableSubscriptions: PurchasableSubscription[];
+    /**
+     * The account balances for the user.
+     *
+     * This will be undefined if the financial controller is not enabled.
+     */
+    accountBalances?: AccountBalances;
 }
 export interface SubscriptionStatus {
     /**
@@ -245,7 +416,7 @@ export interface GetSubscriptionStatusFailure {
     /**
      * The error code.
      */
-    errorCode: ServerError | ValidateSessionKeyFailure['errorCode'] | 'unacceptable_user_id' | 'unacceptable_studio_id' | 'unacceptable_request' | 'not_supported';
+    errorCode: KnownErrorCodes;
     /**
      * The error message.
      */
@@ -316,4 +487,506 @@ export interface UpdateSubscriptionFailure {
     errorCode: ServerError | NotLoggedInError | NotAuthorizedError | 'user_not_found' | 'studio_not_found' | 'invalid_request';
     errorMessage: string;
 }
+export interface CreateManageStoreAccountLinkRequest {
+    /**
+     * The ID of the studio that the link should be created for.
+     */
+    studioId: string;
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+}
+export interface CreateManageXpAccountLinkRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+}
+export interface CreateStripeLoginLinkRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The ID of the studio that the link should be created for.
+     * If not provided, the link will be created for the user's personal account.
+     */
+    studioId?: string;
+}
+export type ManageAccountLinkResult = Result<{
+    /**
+     * The URL that the user can visit to manage their account.
+     */
+    url: string;
+}, SimpleError>;
+export type CreateStripeAccountSessionResult = Result<{
+    /**
+     * The secret token that can be used to access the Stripe account session.
+     */
+    clientSecret: string;
+    /**
+     * The unix time in seconds that the session expires at.
+     */
+    expiresAt: number;
+}, SimpleError>;
+export interface CreatePurchaseItemLinkRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     * Null if the user is not logged in.
+     */
+    userId: string | null;
+    /**
+     * The instances that the request is being made from.
+     */
+    instances: string[];
+    /**
+     * The item that is being purchased.
+     */
+    item: {
+        /**
+         * The name of the record that the item is stored in.
+         */
+        recordName: string;
+        /**
+         * The address of the item.
+         */
+        address: string;
+        /**
+         * The expected cost of the item.
+         */
+        expectedCost: number;
+        /**
+         * The currency that the cost is in.
+         */
+        currency: string;
+    };
+    /**
+     * The URL that the user should be redirected to if the purchase is canceled.
+     */
+    returnUrl: string;
+    /**
+     * The URL that the user should be redirected to if the purchase is unsuccessful.
+     */
+    successUrl: string;
+}
+export type PurchaseContractResult = Result<{
+    /**
+     * The URL that the user should be directed to to complete the purchase.
+     */
+    url?: string;
+    /**
+     * The ID of the checkout session.
+     */
+    sessionId: string;
+}, SimpleError>;
+export type CreatePurchaseItemLinkResult = CreatePurchaseItemLinkSuccess | CreatePurchaseItemLinkFailure;
+export interface CreatePurchaseItemLinkSuccess {
+    success: true;
+    /**
+     * The URL that the user should be redirected to.
+     */
+    url: string;
+    /**
+     * The ID of the checkout session.
+     */
+    sessionId: string;
+}
+export interface CreatePurchaseItemLinkFailure {
+    success: false;
+    errorCode: ServerError | 'invalid_request' | 'not_supported' | 'item_not_found' | 'price_does_not_match' | 'store_disabled' | 'currency_not_supported' | 'subscription_limit_reached' | 'item_already_purchased' | ConstructAuthorizationContextFailure['errorCode'] | AuthorizeSubjectFailure['errorCode'];
+    errorMessage: string;
+    reason?: DenialReason;
+}
+export interface GetContractPricingRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     * Null if the user is not logged in.
+     */
+    userId: string | null;
+    /**
+     * The instances that the request is being made from.
+     */
+    instances: string[];
+    /**
+     * The contract that is being purchased.
+     */
+    contract: {
+        /**
+         * The name of the record that the contract is stored in.
+         */
+        recordName: string;
+        /**
+         * The address of the contract.
+         */
+        address: string;
+    };
+}
+export interface ContractPricing {
+    /**
+     * The information for the contract.
+     */
+    contract: ContractRecord;
+    /**
+     * The total cost to purchase the contract.
+     */
+    total: number;
+    /**
+     * The line items that make up the total cost.
+     */
+    lineItems: ContractPricingLineItem[];
+    /**
+     * The currency that the cost is in.
+     */
+    currency: string;
+}
+export interface ContractPricingLineItem {
+    name: string;
+    amount: number;
+}
+export interface PurchaseContractRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     * Null if the user is not logged in.
+     */
+    userId: string | null;
+    /**
+     * The instances that the request is being made from.
+     */
+    instances: string[];
+    /**
+     * The contract that is being purchased.
+     */
+    contract: {
+        /**
+         * The name of the record that the contract is stored in.
+         */
+        recordName: string;
+        /**
+         * The address of the contract.
+         */
+        address: string;
+        /**
+         * The expected cost of the contract.
+         */
+        expectedCost: number;
+        /**
+         * The currency that the cost is in.
+         */
+        currency: string;
+    };
+    /**
+     * The URL that the user should be redirected to if the purchase is canceled.
+     */
+    returnUrl: string;
+    /**
+     * The URL that the user should be redirected to if the purchase is unsuccessful.
+     */
+    successUrl: string;
+}
+export interface CancelContractRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     * Null if the user is not logged in.
+     */
+    userId: string | null;
+    /**
+     * The instances that the request is being made from.
+     */
+    instances: string[];
+    /**
+     * The name of the record that the contract is stored in.
+     */
+    recordName: string;
+    /**
+     * The address of the contract that is being canceled.
+     */
+    address: string;
+    /**
+     * The ID of the account that the refund should be sent to.
+     * If not provided, then the refund will be sent to the account that owns the contract.
+     */
+    refundAccountId?: string;
+}
+export type CancelContractResult = Result<{
+    /**
+     * The amount that was refunded to the user.
+     */
+    refundedAmount: number;
+    /**
+     * The currency that the refunded amount is in.
+     */
+    refundCurrency: string;
+}, SimpleError>;
+export interface FulfillCheckoutSessionRequest {
+    /**
+     * The ID of the session that should be fulfilled.
+     */
+    sessionId: string;
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string | null;
+    /**
+     * How the session should be fulfilled.
+     * - `now` indicates that the items should be granted to the user and activated imediately.
+     *    Only valid if the user is logged in.
+     * - `later` indicates that an access key should be granted for the user to activate later.
+     */
+    activation: 'now' | 'later';
+}
+export type FulfillCheckoutSessionResult = FulfillCheckoutSessionSuccess | FulfillCheckoutSessionFailure;
+export interface FulfillCheckoutSessionSuccess {
+    success: true;
+    /**
+     * The activation key that the user can use to activate the items later.
+     */
+    activationKey?: string;
+    /**
+     * The URL that the user can visit to activate the items.
+     */
+    activationUrl?: string;
+}
+export interface FulfillCheckoutSessionFailure {
+    success: false;
+    errorCode: ServerError | 'invalid_request' | 'not_supported' | 'not_authorized' | 'not_found';
+    errorMessage: string;
+}
+export interface ClaimActivationKeyRequest {
+    /**
+     * The key that should be claimed.
+     */
+    activationKey: string;
+    /**
+     * The target of the activation key.
+     *
+     * - `guest` indicates that the key should be claimed for a guest user.
+     * - `self` indicates that the key should be claimed for the user that is currently logged in.
+     */
+    target: 'guest' | 'self';
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string | null;
+    /**
+     * The IP Address that the request is coming from.
+     */
+    ipAddress: string;
+}
+export type ClaimActivationKeyResult = ClaimActivationKeySuccess | ClaimActivationKeyFailure;
+export interface ClaimActivationKeySuccess {
+    success: true;
+    /**
+     * The ID of the user that the key was claimed for.
+     */
+    userId: string;
+    /**
+     * The session key that was granted to the new user.
+     */
+    sessionKey?: string;
+    /**
+     * The connection key that was granted to the new user.
+     */
+    connectionKey?: string;
+    /**
+     * The time that the session key will expire.
+     */
+    expireTimeMs?: number;
+}
+export interface ClaimActivationKeyFailure {
+    success: false;
+    errorCode: ServerError | 'invalid_request' | 'not_supported' | 'not_authorized' | 'not_found' | 'not_logged_in';
+    errorMessage: string;
+}
+export interface ListAccountTransfersRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole?: UserRole | null;
+    /**
+     * The ID of the account to list transfers for.
+     */
+    accountId: string | bigint;
+}
+export interface ListedAccountTransfers {
+    accountDetails: FinancialAccount;
+    account: AccountBalance;
+    transfers: AccountTransfer[];
+}
+export interface AccountTransfer {
+    /**
+     * The ID of the transfer.
+     */
+    id: string;
+    /**
+     * The amount of the transfer in the smallest unit of the currency.
+     */
+    amount: bigint;
+    /**
+     * The ID of the account that the transfer was debited from.
+     */
+    debitAccountId: string;
+    /**
+     * The ID of the account that the transfer was credited to.
+     */
+    creditAccountId: string;
+    /**
+     * Whether the transfer is currently pending.
+     */
+    pending: boolean;
+    /**
+     * The code for the transfer.
+     */
+    code: TransferCodes;
+    /**
+     * The time of the transfer in miliseconds since the Unix epoch.
+     */
+    timeMs: number;
+    /**
+     * The ID of the transaction that the transfer belongs to.
+     */
+    transactionId?: string;
+    /**
+     * A helpful note for the transfer.
+     */
+    note?: string;
+}
+export interface GetBalancesRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole?: UserRole | null;
+    /**
+     * The filter that should be used to find the accounts.
+     */
+    filter: FinancialAccountFilter;
+}
+export interface InvoiceContractRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole: UserRole | null;
+    /**
+     * The ID of the contract that should be invoiced.
+     */
+    contractId: string;
+    /**
+     * The amount charged in the invoice.
+     */
+    amount: number;
+    /**
+     * The note that should be included with the invoice.
+     */
+    note: string | null;
+    /**
+     * Where the invoice payment should end up.
+     */
+    payoutDestination: InvoicePayoutDestination;
+}
+export interface PayContractInvoiceRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole: UserRole | null;
+    /**
+     * The ID of the invoice that should be paid.
+     */
+    invoiceId: string;
+}
+export interface VoidContractInvoiceRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole: UserRole | null;
+    /**
+     * The ID of the invoice that should be voided.
+     */
+    invoiceId: string;
+}
+export interface PayoutAccountRequest {
+    /**
+     * The ID of the currently logged in user.
+     */
+    userId: string | null;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole: UserRole | null;
+    /**
+     * The ID of the user that the payout is for.
+     */
+    payoutUserId?: string;
+    /**
+     * The ID of the studio that the payout is for.
+     */
+    payoutStudioId?: string;
+    /**
+     * The amount to payout in the smallest unit of the currency.
+     * If omitted, then the full available balance will be paid out.
+     */
+    payoutAmount?: number;
+    /**
+     * The destination that the payout should be sent to.
+     */
+    payoutDestination: PayoutDestination;
+}
+interface InternalPayoutRequest extends PayoutAccountRequest {
+    /**
+     * The ID of the invoice that the payout is for.
+     */
+    invoiceId?: string;
+    /**
+     * The ID of the contract that the payout is for.
+     */
+    contractId?: string;
+}
+export interface ListContractInvoicesRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole: UserRole | null;
+    /**
+     * The ID of the contract to list invoices for.
+     */
+    contractId: string;
+}
+export interface CancelInvoiceRequest {
+    /**
+     * The ID of the user that is currently logged in.
+     */
+    userId: string;
+    /**
+     * The role of the user that is currently logged in.
+     */
+    userRole: UserRole | null;
+    /**
+     * The ID of the invoice to cancel.
+     */
+    invoiceId: string;
+}
+export {};
 //# sourceMappingURL=SubscriptionController.d.ts.map