@tivio/sdk-react 10.1.0 → 10.2.0

package/README.md

@@ -535,3 +535,87 @@ useTaggedVideos: (tagIds: string[], options?: SubscribeToItemsInRowOptions) => {
     error: Error | null
 }
 ```
+
+### useVoucher hook
+
+Activates a voucher for the current user. Reading vouchers directly from the client is
+forbidden, so the hook does not fetch the voucher — calling `activate()` invokes the
+`activateVoucher` cloud function, which detects on its own whether the code is a single-use
+or a multi-use voucher.
+
+After a successful activation the `voucher` object exposes server-provided metadata
+(`voucherInfo`, `videoId`, `subscriptionsToShow`) as flat attributes. Until the voucher is
+initialized, `voucher` is `null`.
+
+```ts
+/**
+ * Use voucher
+ * @param voucherId - voucher code entered by the user
+ */
+useVoucher: (voucherId: string) => {
+    /**
+     * Triggers the `activateVoucher` cloud function for the current user.
+     * On success, `activationSuccess` becomes `true` and `voucher` is populated
+     * with the activation metadata.
+     */
+    activate: () => Promise<void>
+    voucher: {
+        organizationId: string | null
+        isInitialized: boolean
+        /** Public, server-safe metadata about the activated voucher. */
+        voucherInfo: VoucherInfoPublic | null
+        /** Set for transaction (PPV) vouchers — the unlocked video. */
+        videoId?: string
+        /** Monetizations to offer when the voucher does not fully cover the content. */
+        subscriptionsToShow: PurchasableMonetization[]
+    } | null
+    error: Error | BadRequestError | null
+    activationSuccess: boolean
+}
+```
+
+`voucherInfo` is a discriminated union by `type`:
+
+```ts
+type VoucherInfoPublic = VoucherInfoSubscriptionPublic | VoucherInfoTransactionPublic
+
+interface VoucherInfoBasePublic {
+    id: string
+    isExpired: boolean
+    status: 'NEW' | 'USED' | 'FULFILLED'
+    /** True when the voucher fully covers the content (no further payment needed). */
+    fullDiscount?: boolean
+}
+
+interface VoucherInfoSubscriptionPublic extends VoucherInfoBasePublic {
+    type: 'subscription'
+    name: string
+    benefits: string[]
+    frequency?: MONETIZATION_FREQUENCY
+}
+
+interface VoucherInfoTransactionPublic extends VoucherInfoBasePublic {
+    type: 'transaction'
+    name: string
+    videoId: string
+    cover: string
+    description: string
+}
+```
+
+When activation fails, `error` may be a `BadRequestError` whose `details.reason` explains why:
+
+```ts
+type BadRequestError = Error & {
+    details?: {
+        reason?:
+            | 'DOES_NOT_EXIST'
+            | 'EXPIRED'
+            | 'ALREADY_USED'
+            | 'ALREADY_USED_BY_CURRENT_USER'
+            | 'LIMIT_REACHED'
+            | 'FULFILLED'
+            | 'INVALID_VOUCHER_TYPE'
+    }
+}
+```

package/README.md.bak

@@ -535,3 +535,87 @@ useTaggedVideos: (tagIds: string[], options?: SubscribeToItemsInRowOptions) => {
     error: Error | null
 }
 ```
+
+### useVoucher hook
+
+Activates a voucher for the current user. Reading vouchers directly from the client is
+forbidden, so the hook does not fetch the voucher — calling `activate()` invokes the
+`activateVoucher` cloud function, which detects on its own whether the code is a single-use
+or a multi-use voucher.
+
+After a successful activation the `voucher` object exposes server-provided metadata
+(`voucherInfo`, `videoId`, `subscriptionsToShow`) as flat attributes. Until the voucher is
+initialized, `voucher` is `null`.
+
+```ts
+/**
+ * Use voucher
+ * @param voucherId - voucher code entered by the user
+ */
+useVoucher: (voucherId: string) => {
+    /**
+     * Triggers the `activateVoucher` cloud function for the current user.
+     * On success, `activationSuccess` becomes `true` and `voucher` is populated
+     * with the activation metadata.
+     */
+    activate: () => Promise<void>
+    voucher: {
+        organizationId: string | null
+        isInitialized: boolean
+        /** Public, server-safe metadata about the activated voucher. */
+        voucherInfo: VoucherInfoPublic | null
+        /** Set for transaction (PPV) vouchers — the unlocked video. */
+        videoId?: string
+        /** Monetizations to offer when the voucher does not fully cover the content. */
+        subscriptionsToShow: PurchasableMonetization[]
+    } | null
+    error: Error | BadRequestError | null
+    activationSuccess: boolean
+}
+```
+
+`voucherInfo` is a discriminated union by `type`:
+
+```ts
+type VoucherInfoPublic = VoucherInfoSubscriptionPublic | VoucherInfoTransactionPublic
+
+interface VoucherInfoBasePublic {
+    id: string
+    isExpired: boolean
+    status: 'NEW' | 'USED' | 'FULFILLED'
+    /** True when the voucher fully covers the content (no further payment needed). */
+    fullDiscount?: boolean
+}
+
+interface VoucherInfoSubscriptionPublic extends VoucherInfoBasePublic {
+    type: 'subscription'
+    name: string
+    benefits: string[]
+    frequency?: MONETIZATION_FREQUENCY
+}
+
+interface VoucherInfoTransactionPublic extends VoucherInfoBasePublic {
+    type: 'transaction'
+    name: string
+    videoId: string
+    cover: string
+    description: string
+}
+```
+
+When activation fails, `error` may be a `BadRequestError` whose `details.reason` explains why:
+
+```ts
+type BadRequestError = Error & {
+    details?: {
+        reason?:
+            | 'DOES_NOT_EXIST'
+            | 'EXPIRED'
+            | 'ALREADY_USED'
+            | 'ALREADY_USED_BY_CURRENT_USER'
+            | 'LIMIT_REACHED'
+            | 'FULFILLED'
+            | 'INVALID_VOUCHER_TYPE'
+    }
+}
+```

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import type { ComponentType } from 'react';
 import { DocumentReference } from '@firebase/firestore-types';
 import type duration from 'dayjs/plugin/duration';
-import type { default as firebase_2 } from '@firebase/app-types';
-import type { default as firebase_3 } from 'firebase';
+import type firebase from '@firebase/app-types';
 import { FunctionComponentElement } from 'react';
 import type { GeoPoint } from '@firebase/firestore-types';
 import { OperatingSystem } from 'detect-browser';
@@ -26,7 +25,22 @@ export declare interface ActivatedPromotionsWithIdsResponse {
     activatedPromotionsIds: string[];
 }
 
-export declare type ActivateVoucherResponse = string | ActivatedPromotionsResponse | ActivatedPromotionsWithIdsResponse;
+/**
+ * Response returned when `activateVoucher` is called with `responseFormat: 'extended'`.
+ *
+ * It always carries `voucherInfo` (safe server-side metadata) and, depending on the
+ * voucher type, either a `purchaseId` (transaction / subscription) or the list of
+ * `activatedPromotions` (promotion voucher).
+ */
+export declare interface ActivateVoucherExtendedResponse {
+    voucherInfo: VoucherInfoPublic;
+    purchaseId?: string;
+    activatedPromotions?: ActivatedPromotion[];
+}
+
+export declare type ActivateVoucherResponse = string | ActivatedPromotionsResponse | ActivatedPromotionsWithIdsResponse | ActivateVoucherExtendedResponse;
+
+export declare type ActivateVoucherResponseFormat = 'legacy' | 'extended';
 
 declare interface actualPriceDetails {
     amountCents: number;
@@ -599,7 +613,7 @@ export declare interface AvatarProps {
  */
 export declare type BadRequestError = Error & {
     details?: {
-        reason?: 'DOES_NOT_EXIST' | 'EXPIRED' | 'ALREADY_USED' | 'ALREADY_USED_BY_CURRENT_USER';
+        reason?: 'DOES_NOT_EXIST' | 'EXPIRED' | 'ALREADY_USED' | 'ALREADY_USED_BY_CURRENT_USER' | 'LIMIT_REACHED' | 'FULFILLED' | 'INVALID_VOUCHER_TYPE';
     };
 };
 
@@ -1456,7 +1470,9 @@ export declare enum CustomerId {
     THE_JOHNY = "THE_JOHNY",
     GOOD_MOVE = "GOOD_MOVE",
     JANA_HANZ = "JANA_HANZ",
-    MYSTICO = "MYSTICO"
+    MYSTICO = "MYSTICO",
+    MORAVEC = "MORAVEC",
+    JAN_TUNA = "JAN_TUNA"
 }
 
 export declare interface CustomScript {
@@ -3227,6 +3243,16 @@ export declare interface MonetizationCardProps {
     focused?: boolean;
 }
 
+/**
+ * @public
+ */
+export declare type MonetizationCta = {
+    type: 'email';
+    payload: {
+        email: string;
+    };
+};
+
 export declare interface MonetizationsCountsSummaryItem {
     /**
      * Unix timestamp at which the data is aggregated
@@ -4617,6 +4643,11 @@ export declare interface PubSub {
  * @public
  */
 export declare interface PurchasableMonetization extends Monetization {
+    /**
+     * If CTA is configured, the monetization should not be directly purchasable in clients.
+     * Client apps should render CTA action instead of purchase button.
+     */
+    cta?: MonetizationCta;
     /**
      * Price before any discounts (e.g. promotions).
      */
@@ -6594,14 +6625,6 @@ export declare type SubscribeToTaggedVideosOptions = Omit<SubscribeToItemsInRowO
     orderBy?: OrderBy<TaggedVideosOrderByField>[];
 };
 
-declare interface SubscriptionInfo {
-    id: string;
-    type: 'subscription';
-    name: string;
-    benefits: string[];
-    frequency: string;
-}
-
 /**
  * Extended language codes for subtitle tracks.
  * Includes all LangCode values plus additional languages only needed for subtitles.
@@ -6984,7 +7007,7 @@ export declare interface TivioConfig {
     debug?: boolean;
     verbose?: boolean;
     firebaseApp?: any | null;
-    firebaseFactory?: (config: object, appName?: string) => firebase_2.FirebaseApp;
+    firebaseFactory?: (config: object, appName?: string) => firebase.FirebaseApp;
     authDomainOverride?: string;
     /**
      * @deprecated this field is no longer in use and has no impact when set.
@@ -7113,7 +7136,7 @@ export declare type TivioHooks = {
         data: Video | null;
         error: string | null;
     };
-    useVoucher: (voucherId: string) => any;
+    useVoucher: (voucherId: string) => UseVoucherReturn;
     useApplyInviteCode: () => {
         applyInviteCodeResult?: boolean;
         loading: boolean;
@@ -7356,7 +7379,7 @@ export declare type TivioReactBundle = {
     }, email?: string) => Promise<QerkoPaymentInfo>;
     purchaseSubscriptionWithQerko: (monetizationId: string, voucher?: {
         expirationDate: Date;
-    }) => Promise<QerkoPaymentInfo>;
+    }, email?: string, quantity?: number) => Promise<QerkoPaymentInfo>;
     cancelSubscriptionWithQerko: (subscriptionId: string) => Promise<QerkoCancellationInfo>;
     showConsentPreferences: () => void;
     /**
@@ -7465,17 +7488,6 @@ export declare interface Track {
     language: LangCode;
 }
 
-declare interface TransactionInfo {
-    id: string;
-    type: 'transaction';
-    name: string;
-    videoId: string;
-    cover: string;
-    description: string;
-    promotions?: firebase_3.firestore.DocumentReference<Promotion>[];
-    fullDiscount?: boolean;
-}
-
 /**
  * Represents one string in every supported language mutation.
  * @public
@@ -8324,19 +8336,28 @@ export declare const useVideo: (videoIdOrUrlName?: string) => {
 /**
  * @public
  */
-export declare const useVoucher: (voucherId: string) => {
-    activate: (() => Promise<void>) | null;
-    voucher: Voucher | null;
-    /**
-     * You can check error.details if you need to know error type when you want your own error messages
-     * (can be one of "DOES_NOT_EXIST", "EXPIRED", "ALREADY_USED_BY_CURRENT_USER" and "ALREADY_USED").
-     */
-    error: Error | BadRequestError | null;
-    /**
-     * True if voucher has been successfully activated in current session.
-     */
+export declare const useVoucher: (voucherId: string) => UseVoucherReturn;
+
+/**
+ * Return type of `useVoucher` hook (core-react / sdk-react).
+ *
+ * Activation is triggered via the top-level `activate`. After a successful activation
+ * `voucher` carries the server-provided metadata (`voucherInfo`, `videoId`,
+ * `subscriptionsToShow`) as flat attributes. While the voucher is still initializing,
+ * `voucher` is `null`.
+ */
+export declare interface UseVoucherReturn {
+    activate: () => Promise<void>;
+    voucher: {
+        organizationId: string | null;
+        isInitialized: boolean;
+        voucherInfo: VoucherInfoPublic | null;
+        videoId?: string;
+        subscriptionsToShow: PurchasableMonetization[];
+    } | null;
+    error: Error | null;
     activationSuccess: boolean;
-};
+}
 
 /**
  * @public
@@ -8970,15 +8991,30 @@ export declare interface VodTivioSourceParams extends PlayerSourceParams<SourceT
     sessionId?: string;
 }
 
-/**
- * TODO: Should be in core-js, we can't import types from it, though.
- */
-declare interface Voucher {
-    activate: () => void;
-    isUsed: boolean;
+export declare interface VoucherInfoBasePublic {
+    id: string;
     isExpired: boolean;
-    status: 'NEW' | 'USED';
-    voucherInfo: SubscriptionInfo | TransactionInfo;
+    status: VoucherInfoPublicStatus;
+    fullDiscount?: boolean;
+}
+
+export declare type VoucherInfoPublic = VoucherInfoSubscriptionPublic | VoucherInfoTransactionPublic;
+
+export declare type VoucherInfoPublicStatus = 'NEW' | 'USED' | 'FULFILLED';
+
+export declare interface VoucherInfoSubscriptionPublic extends VoucherInfoBasePublic {
+    type: 'subscription';
+    name: string;
+    benefits: string[];
+    frequency?: MONETIZATION_FREQUENCY;
+}
+
+export declare interface VoucherInfoTransactionPublic extends VoucherInfoBasePublic {
+    type: 'transaction';
+    name: string;
+    videoId: string;
+    cover: string;
+    description: string;
 }
 
 declare interface VoucherPageConfiguration {