@freemius/sdk 0.0.5 → 0.1.0

package/README.md

@@ -56,7 +56,7 @@ your front-end to quickly render Checkout overlays, pricing tables, and a custom
 ## Installation
 
 ```bash
-npm install @freemius/sdk zod
+npm install @freemius/sdk @freemius/checkout zod
 ```
 
 Requires Node.js 18+ (or an Edge runtime supporting Web Crypto + standard fetch APIs). See the

package/dist/index.d.mts

@@ -12935,6 +12935,7 @@ type PlanEntity = components['schemas']['Plan'];
 type BillingEntity = components['schemas']['Billing'];
 type BillingUpdatePayload = operations['users/update-or-create-billing']['requestBody']['content']['application/json'];
 type EventEntity = components['schemas']['EventLog'];
+type EventFilterOptions = ApiEntitiesFilter<operations['events/list']['parameters']['query']>;
 type InstallEntity = components['schemas']['Install'];
 type BillingCycleApiEnum = components['schemas']['CommonEnums']['BillingCycle'];
 type CurrencyApiEnum = components['schemas']['CommonEnums']['Currency'];
@@ -13195,9 +13196,9 @@ interface CheckoutRedirectData {
    */
   pricing_id: string;
   /**
-   * Currency of the purchase (ISO code).
+   * Indicates the type of action performed during checkout.
    */
-  currency: CURRENCY;
+  action: 'payment_method_update' | 'license_update' | 'trial' | 'purchase';
   /**
    * ID of the Freemius license, if available.
    */
@@ -13211,12 +13212,17 @@ interface CheckoutRedirectData {
    */
   quota: number | null;
   /**
-   * Indicates the type of action performed during checkout, if applicable.
-   * Can be 'payment_method_update' or 'license_update'.
-   *
-   * If null it means the checkout was a standard purchase.
+   * Indicates if the trial is free or paid. Null if not a trial.
+   */
+  trial: 'free' | 'paid' | null;
+  /**
+   * End date of the trial period, if applicable.
+   */
+  trial_ends_at: Date | null;
+  /**
+   * Currency of the purchase (ISO code).
    */
-  action: 'payment_method_update' | 'license_update' | null;
+  currency: CURRENCY;
   /**
    * Total amount charged for the purchase.
    */
@@ -13225,18 +13231,6 @@ interface CheckoutRedirectData {
    * Tax amount applied to the purchase.
    */
   tax: number;
-  /**
-   * Indicates a subscription purchase.
-   * If present, the following fields are required:
-   * - type: 'subscription'
-   * - subscription_id
-   * - billing_cycle
-   *
-   * If not present, the purchase is a one-off and the following fields are required:
-   * - type: 'one-off'
-   * - payment_id
-   */
-  type: 'subscription' | 'one-off';
   /**
    * ID of the Freemius subscription associated with the license (for subscriptions only).
    */
@@ -13249,6 +13243,20 @@ interface CheckoutRedirectData {
    * ID of the payment for the one-off purchase (for one-off only).
    */
   payment_id: string | null;
+  /**
+   * Indicates a subscription purchase.
+   * If present, the following fields are required:
+   * - type: 'subscription'
+   * - subscription_id
+   * - billing_cycle
+   *
+   * If not present, the purchase is a one-off and the following fields are required:
+   * - type: 'one-off'
+   * - payment_id
+   *
+   * If null, indicates this is a free trial purchase and the final type of purchase is not applicable.
+   */
+  type: 'subscription' | 'one-off' | null;
 }
 type CheckoutBuilderUserOptions = {
   email: string;
@@ -13301,6 +13309,12 @@ type CheckoutBuilderOptions = {
    * If not provided, the checkout will not have a trial period.
    */
   trial?: CheckoutOptions['trial'];
+  /**
+   * Optional license ID for license upgrade scenarios.
+   *
+   * When provided, the checkout will be configured for upgrading the specified license. Use this to generate upgrade links for existing users.
+   */
+  licenseId?: string;
 };
 /**
  * Interface for actions that can be processed during the checkout flow.
@@ -13332,6 +13346,20 @@ type PricingData = {
   sellingUnit: SellingUnit;
 };
 //#endregion
+//#region src/contracts/webhook.d.ts
+type WebhookListenerResponse = {
+  status: number;
+} & ({
+  success: true;
+} | {
+  success: false;
+  error: string;
+});
+declare enum WebhookAuthenticationMethod {
+  SignatureHeader = "SignatureHeader",
+  Api = "Api",
+}
+//#endregion
 //#region src/api/parser.d.ts
 declare function idToNumber(id: FSId): number;
 declare function idToString(id: FSId): string;
@@ -13343,6 +13371,26 @@ declare function parseDate(dateString?: string | null): Date | null;
 declare function parseCurrency(currency?: CurrencyApiEnum): CURRENCY | null;
 declare function parsePaymentMethod(gateway?: string | null): PaymentMethod | null;
 //#endregion
+//#region src/errors/ActionError.d.ts
+declare class ActionError extends Error {
+  readonly statusCode: number;
+  readonly validationIssues?: unknown;
+  constructor(message: string, statusCode?: number, validationIssues?: unknown);
+  toResponse(): Response;
+  static badRequest(message: string): ActionError;
+  static unauthorized(message?: string): ActionError;
+  static notFound(message?: string): ActionError;
+  static validationFailed(message: string, validationIssues: unknown): ActionError;
+  static internalError(message?: string): ActionError;
+}
+//#endregion
+//#region src/errors/WebhookError.d.ts
+declare class WebhookError extends Error {
+  readonly statusCode: number;
+  constructor(message: string, statusCode?: number);
+  toResponse(): WebhookListenerResponse;
+}
+//#endregion
 //#region src/api/client.d.ts
 declare function createApiClient(baseUrl: string, bearerToken?: string): createClient.Client<paths, `${string}/${string}`>;
 type FsApiClient = ReturnType<typeof createApiClient>;
@@ -13619,6 +13667,48 @@ declare class Payment extends ApiBase<PaymentEntity, PaymentFilterOptions> {
   retrieveInvoice(paymentId: FSId): Promise<Blob | null>;
 }
 //#endregion
+//#region src/api/WebhookEvent.d.ts
+declare class WebhookEvent$1 extends ApiBase<EventEntity, EventFilterOptions> {
+  retrieve(eventId: FSId): Promise<({
+    state?: components["schemas"]["CommonEnums"]["EventLogState"];
+    id?: components["schemas"]["CommonProperties"]["id"];
+    created?: components["schemas"]["CommonProperties"]["created"];
+    updated?: components["schemas"]["CommonProperties"]["updated"];
+    type?: string;
+    developer_id?: string;
+    plugin_id?: components["schemas"]["CommonProperties"]["plugin_id_nullable"];
+    user_id?: components["schemas"]["CommonProperties"]["user_id_nullable"];
+    install_id?: components["schemas"]["CommonProperties"]["install_id_nullable"];
+    data?: unknown;
+    event_trigger?: "system" | "developer" | "plugin" | "user" | "install";
+    process_time?: string | null;
+  } & {
+    objects?: {
+      user?: components["schemas"]["UserPluginEnriched"] | null;
+      install?: components["schemas"]["Install"] | null;
+      payment?: components["schemas"]["Payment"] | null;
+      subscription?: components["schemas"]["Subscription"] | null;
+      license?: components["schemas"]["License"] | null;
+    } & {
+      [key: string]: unknown;
+    };
+  }) | null>;
+  retrieveMany(filter?: EventFilterOptions, pagination?: PagingOptions): Promise<{
+    state?: components["schemas"]["CommonEnums"]["EventLogState"];
+    id?: components["schemas"]["CommonProperties"]["id"];
+    created?: components["schemas"]["CommonProperties"]["created"];
+    updated?: components["schemas"]["CommonProperties"]["updated"];
+    type?: string;
+    developer_id?: string;
+    plugin_id?: components["schemas"]["CommonProperties"]["plugin_id_nullable"];
+    user_id?: components["schemas"]["CommonProperties"]["user_id_nullable"];
+    install_id?: components["schemas"]["CommonProperties"]["install_id_nullable"];
+    data?: unknown;
+    event_trigger?: "system" | "developer" | "plugin" | "user" | "install";
+    process_time?: string | null;
+  }[]>;
+}
+//#endregion
 //#region src/services/ApiService.d.ts
 /**
  * @todo - Add a proper user-agent string with SDK version.
@@ -13633,6 +13723,7 @@ declare class ApiService {
   readonly product: Product;
   readonly subscription: Subscription;
   readonly payment: Payment;
+  readonly event: WebhookEvent$1;
   readonly baseUrl: string;
   constructor(productId: FSId, apiKey: string, secretKey: string, publicKey: string);
   /**
@@ -13668,6 +13759,10 @@ type CheckoutSerialized = {
   link: string;
   baseUrl: string;
 };
+type CheckoutLicenseAuthorization = {
+  licenseId: FSId;
+  authorization: string;
+};
 /**
  * A builder class for constructing checkout parameters. This class provides a fluent
  * API to create Checkout parameters for a product with various configurations.
@@ -13679,43 +13774,37 @@ declare class Checkout {
   private readonly productId;
   private readonly publicKey;
   private readonly secretKey;
-  static createSandboxToken(productId: string, secretKey: string, publicKey: string): NonNullable<CheckoutPopupParams['sandbox']>;
   private options;
   constructor(productId: string, publicKey: string, secretKey: string);
   /**
    * Enables sandbox mode for testing purposes.
    *
-   * @returns A new builder instance with sandbox configuration
    */
-  setSandbox(): Checkout;
+  setSandbox(sandbox: NonNullable<CheckoutPopupParams['sandbox']>): Checkout;
   /**
    * Sets user information for the checkout session.
    *
    * @param user User object with email and optional name fields. The shape matches the session from `better-auth` or next-auth packages. Also handles `null` or `undefined` gracefully.
    * @param readonly If true, the user information will be read-only in the checkout session.
    *
-   * @returns A new builder instance with user configuration
    */
   setUser(user: CheckoutBuilderUserOptions, readonly?: boolean): Checkout;
   /**
    * Applies recommended UI settings for better user experience.
    * This includes fullscreen mode, upsells, refund badge, and reviews display.
    *
-   * @returns A new builder instance with recommended UI settings
    */
   setRecommendations(): Checkout;
   /**
    * Sets the plan ID for the checkout.
    *
    * @param planId The plan ID to purchase
-   * @returns A new builder instance with plan ID set
    */
   setPlan(planId: string | number): Checkout;
   /**
    * Sets the number of licenses to purchase.
    *
    * @param count Number of licenses
-   * @returns A new builder instance with license count set
    */
   setQuota(count: number): Checkout;
   setPricing(pricingId: string | number): Checkout;
@@ -13725,7 +13814,6 @@ declare class Checkout {
    *
    * @param coupon The coupon code to apply
    * @param hideUI Whether to hide the coupon input field from users
-   * @returns A new builder instance with coupon configuration
    */
   setCoupon(options: {
     code: string;
@@ -13735,14 +13823,12 @@ declare class Checkout {
    * Enables trial mode for the checkout.
    *
    * @param mode Trial type - true/false for plan default, or specific 'free'/'paid' mode
-   * @returns A new builder instance with trial configuration
    */
   setTrial(mode?: 'free' | 'paid' | boolean): Checkout;
   /**
    * Configures the visual layout and appearance of the checkout.
    *
    * @param options Appearance configuration options
-   * @returns A new builder instance with appearance configuration
    */
   setAppearance(options: {
     layout?: 'vertical' | 'horizontal' | null;
@@ -13755,7 +13841,6 @@ declare class Checkout {
    * Configures discount display settings.
    *
    * @param options Discount configuration options
-   * @returns A new builder instance with discount configuration
    */
   setDiscounts(options: {
     annual?: boolean;
@@ -13768,21 +13853,18 @@ declare class Checkout {
    *
    * @param selector Type of billing cycle selector to show
    * @param defaultCycle Default billing cycle to select
-   * @returns A new builder instance with billing cycle configuration
    */
   setBillingCycle(defaultCycle: 'monthly' | 'annual' | 'lifetime', selector?: 'list' | 'responsive_list' | 'dropdown'): Checkout;
   /**
    * Sets the language/locale for the checkout.
    *
    * @param locale Language setting - 'auto', 'auto-beta', or specific locale like 'en_US'
-   * @returns A new builder instance with locale configuration
    */
   setLanguage(locale?: 'auto' | 'auto-beta' | string): Checkout;
   /**
    * Configures review and badge display settings.
    *
    * @param options Review and badge configuration
-   * @returns A new builder instance with reviews and badges configuration
    */
   setSocialProofing(options: {
     showReviews?: boolean;
@@ -13796,7 +13878,6 @@ declare class Checkout {
    * @param currency Primary currency or 'auto' for automatic detection
    * @param defaultCurrency Default currency when using 'auto'
    * @param showInlineSelector Whether to show inline currency selector
-   * @returns A new builder instance with currency configuration
    */
   setCurrency(currency: 'usd' | 'eur' | 'gbp' | 'auto', defaultCurrency?: 'usd' | 'eur' | 'gbp', showInlineSelector?: boolean): Checkout;
   /**
@@ -13804,42 +13885,42 @@ declare class Checkout {
    *
    * @param cancelUrl URL for back button when in page mode
    * @param cancelIcon Custom cancel icon URL
-   * @returns A new builder instance with navigation configuration
    */
   setCancelButton(cancelUrl?: string, cancelIcon?: string): Checkout;
   /**
    * Associates purchases with an affiliate account.
    *
    * @param userId Affiliate user ID
-   * @returns A new builder instance with affiliate configuration
    */
   setAffiliate(userId: number): Checkout;
   /**
    * Sets a custom image/icon for the checkout.
    *
    * @param imageUrl Secure HTTPS URL to the image
-   * @returns A new builder instance with custom image
    */
   setImage(imageUrl: string): Checkout;
   /**
-   * Configures the checkout for license renewal.
+   * Configures the checkout for license renewal or upgrade by the license key.
+   *
+   * @note - This is less secure since it exposes the license key to the client. Use only in authenticated contexts.
    *
    * @param licenseKey The license key to renew
-   * @returns A new builder instance configured for renewal
    */
-  setLicenseRenewal(licenseKey: string): Checkout;
+  setLicenseUpgradeByKey(licenseKey: string): Checkout;
   /**
-   * Builds and returns the final checkout options to be used with the `@freemius/checkout` package.
+   * Configures the checkout for license upgrade using an authorization token.
    *
-   * @note - This is async by purpose so that we can allow for future enhancements that might require async operations.
+   * @param params The license upgrade authorization parameters
+   */
+  setLicenseUpgradeByAuth(params: CheckoutLicenseAuthorization): Checkout;
+  /**
+   * Builds and returns the final checkout options to be used with the `@freemius/checkout` package.
    *
    * @returns The constructed CheckoutOptions object
    */
   getOptions(): CheckoutOptions;
   /**
    * Generates a checkout link based on the current builder state.
-   *
-   * @note - This is async by purpose so that we can allow for future enhancements that might require async operations.
    */
   getLink(): string;
   serialize(): CheckoutSerialized;
@@ -13949,14 +14030,16 @@ declare class CheckoutRedirectInfo implements CheckoutRedirectData {
   plan_id: string;
   email: string;
   pricing_id: string;
-  currency: CURRENCY;
+  action: 'payment_method_update' | 'license_update' | 'trial' | 'purchase';
   license_id: string;
   expiration: Date | null;
   quota: number | null;
-  action: 'payment_method_update' | 'license_update' | null;
+  trial: 'free' | 'paid' | null;
+  trial_ends_at: Date | null;
+  currency: CURRENCY;
   amount: number;
   tax: number;
-  type: 'subscription' | 'one-off';
+  type: 'subscription' | 'one-off' | null;
   subscription_id: string | null;
   billing_cycle: BILLING_CYCLE | null;
   payment_id: string | null;
@@ -14047,13 +14130,14 @@ declare class CheckoutRequestProcessor implements RequestProcessor<CheckoutReque
 //#endregion
 //#region src/services/CheckoutService.d.ts
 declare class CheckoutService {
+  private readonly api;
   private readonly productId;
   private readonly publicKey;
   private readonly secretKey;
   private readonly purchase;
   private readonly pricing;
   readonly request: CheckoutRequestProcessor;
-  constructor(productId: FSId, publicKey: string, secretKey: string, purchase: PurchaseService, pricing: PricingService);
+  constructor(api: ApiService, productId: FSId, publicKey: string, secretKey: string, purchase: PurchaseService, pricing: PricingService);
   /**
    * Use this to build a Checkout for your product.
    * You can build a Checkout link or options for the popup.
@@ -14093,11 +14177,14 @@ declare class CheckoutService {
    * This shouldn't be used in production, but is useful for testing purposes.
    *
    * @note This is intentionally set as `async` because we would use the API in the future to generate more fine grained sandbox params (for example for a specific email address only).
-   *
-   * @todo - This has a duplication with the `inSandbox` method in the builder. Consider refactoring to avoid this duplication.
-   *         Also think about whether we should make the builder's `inSandbox` method async as well.
    */
   getSandboxParams(): Promise<NonNullable<CheckoutPopupParams['sandbox']>>;
+  /**
+   * Retrieves the license upgrade authorization for a given license ID.
+   *
+   * This is used to authorize a license upgrade during the checkout process. Useful when creating upgrade links for existing users.
+   */
+  getLicenseUpgradeAuth(licenseId: FSId): Promise<CheckoutLicenseAuthorization>;
   /**
    * Processes a redirect URL and returns the checkout redirect information if valid.
    *
@@ -14600,19 +14687,13 @@ interface NormalizedRequest {
   headers: Record<string, string | string[] | undefined> | Headers;
   rawBody: string | Buffer;
 }
-type WebhookListenerResponse = {
-  status: number;
-} & ({
-  success: true;
-} | {
-  success: false;
-  error: string;
-});
 declare class WebhookListener {
+  private readonly api;
   private readonly secretKey;
   private readonly onError;
+  private readonly authenticationMethod;
   private eventHandlers;
-  constructor(secretKey: string, onError?: (error: unknown) => void);
+  constructor(api: ApiService, secretKey: string, onError?: (error: unknown) => Promise<void>, authenticationMethod?: WebhookAuthenticationMethod);
   on<T extends WebhookEventType>(type: T, handler: WebhookEventHandler<T>): this;
   on<T extends WebhookEventType>(types: T[], handler: WebhookEventHandler<T>): this;
   off<T extends WebhookEventType>(type: T, handler: WebhookEventHandler<T>): this;
@@ -14634,14 +14715,23 @@ declare class WebhookListener {
    * Returns an object you can map to your framework's response easily.
    */
   process(input: NormalizedRequest): Promise<WebhookListenerResponse>;
+  private authenticateAndGetEventFromInput;
+  private authenticateAndGetEventFromApi;
+  private parseEventFromInput;
+  private processEvent;
   private getHeader;
 }
 //#endregion
 //#region src/services/WebhookService.d.ts
+type WebhookListenerConfig = {
+  onError?: (error: unknown) => Promise<void>;
+  authenticationMethod?: WebhookAuthenticationMethod;
+};
 declare class WebhookService {
+  private readonly api;
   private readonly secretKey;
-  constructor(secretKey: string);
-  createListener(onError?: (error: unknown) => void): WebhookListener;
+  constructor(api: ApiService, secretKey: string);
+  createListener(config?: WebhookListenerConfig): WebhookListener;
   createRequestProcessor(listener: WebhookListener): (request: Request) => Promise<Response>;
   /**
    * WHATWG Fetch API adapter for modern JavaScript environments.
@@ -14755,5 +14845,5 @@ declare class Freemius {
   constructor(config: FreemiusConfig);
 }
 //#endregion
-export { ApiAuthParams, ApiEntitiesFilter, type ApiService, type ApplyRenewalCouponRequest, BILLING_CYCLE, BillingCycleApiEnum, BillingEntity, type BillingRequest, BillingUpdatePayload, CURRENCY, type Checkout, CheckoutAction, type CheckoutRequestConfig as CheckoutActionConfig, CheckoutBuilderOptions, CheckoutBuilderUserOptions, CheckoutRedirectData, type CheckoutRedirectInfo, type CheckoutSerialized, type CheckoutService, CouponEntityEnriched, CurrencyApiEnum, type CustomerPortalDataWithEmailOption, type CustomerPortalDataWithUserOption, type CustomerPortalService, EventEntity, FSId, Freemius, FreemiusConfig, InstallEntity, LicenseEntity, LicenseFilterOptions, PagingOptions, PaymentEntity, PaymentFilterOptions, PaymentMethod, PlanEntity, PortalAction, PortalBilling, PortalData, PortalPayment, PortalPlans, type PortalRequestConfig, PortalSubscription, PortalSubscriptions, PricingData, PricingEntity, type PricingService, PricingTableData, ProductEntity, PurchaseData, PurchaseEntitlementData, PurchaseEntitlementType, type PurchaseInfo, type PurchaseService, RequestProcessor, SellingUnit, SubscriptionCancellationReasonType, type SubscriptionCancellationRequest, SubscriptionCancellationResult, SubscriptionDiscountEntity, SubscriptionEntity, SubscriptionFilterOptions, SubscriptionRenewalCouponResult, UserBillingEntity, UserEntity, UserFilterOptions, UserLicenseFilterOptions, UserPaymentFilterOptions, UserPluginEntity, UserRetriever, UserSubscriptionEntity, UserSubscriptionFilterOptions, UserSubscriptionWithDiscounts, type WebhookEvent, type WebhookEventDataMap, type WebhookEventHandler, type WebhookEventType, type WebhookService, idToNumber, idToString, isIdsEqual, parseBillingCycle, parseCurrency, parseDate, parseDateTime, parseNumber, parsePaymentMethod };
+export { ActionError, ApiAuthParams, ApiEntitiesFilter, type ApiService, type ApplyRenewalCouponRequest, BILLING_CYCLE, BillingCycleApiEnum, BillingEntity, type BillingRequest, BillingUpdatePayload, CURRENCY, type Checkout, CheckoutAction, type CheckoutRequestConfig as CheckoutActionConfig, CheckoutBuilderOptions, CheckoutBuilderUserOptions, CheckoutRedirectData, type CheckoutRedirectInfo, type CheckoutSerialized, type CheckoutService, CouponEntityEnriched, CurrencyApiEnum, type CustomerPortalDataWithEmailOption, type CustomerPortalDataWithUserOption, type CustomerPortalService, EventEntity, EventFilterOptions, FSId, Freemius, FreemiusConfig, InstallEntity, LicenseEntity, LicenseFilterOptions, PagingOptions, PaymentEntity, PaymentFilterOptions, PaymentMethod, PlanEntity, PortalAction, PortalBilling, PortalData, PortalPayment, PortalPlans, type PortalRequestConfig, PortalSubscription, PortalSubscriptions, PricingData, PricingEntity, type PricingService, PricingTableData, ProductEntity, PurchaseData, PurchaseEntitlementData, PurchaseEntitlementType, type PurchaseInfo, type PurchaseService, RequestProcessor, SellingUnit, SubscriptionCancellationReasonType, type SubscriptionCancellationRequest, SubscriptionCancellationResult, SubscriptionDiscountEntity, SubscriptionEntity, SubscriptionFilterOptions, SubscriptionRenewalCouponResult, UserBillingEntity, UserEntity, UserFilterOptions, UserLicenseFilterOptions, UserPaymentFilterOptions, UserPluginEntity, UserRetriever, UserSubscriptionEntity, UserSubscriptionFilterOptions, UserSubscriptionWithDiscounts, WebhookAuthenticationMethod, WebhookError, type WebhookEvent, type WebhookEventDataMap, type WebhookEventHandler, type WebhookEventType, WebhookListenerResponse, type WebhookService, idToNumber, idToString, isIdsEqual, parseBillingCycle, parseCurrency, parseDate, parseDateTime, parseNumber, parsePaymentMethod };
 //# sourceMappingURL=index.d.mts.map