@tivio/sdk-react 10.0.0 → 10.2.0

package/README.md

@@ -8,9 +8,9 @@ settings in the administration of Tivio Studio while having the freedom to build
 
 Install @tivio/sdk-react along with its peer dependencies
 ```sh
-npm i react@17 react-dom@17 @tivio/sdk-react
+npm i react@18 react-dom@18 @tivio/sdk-react
 # or
-yarn add react@17 react-dom@17 @tivio/sdk-react
+yarn add react@18 react-dom@18 @tivio/sdk-react
 ```
 
 ## Initialization
@@ -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

@@ -8,9 +8,9 @@ settings in the administration of Tivio Studio while having the freedom to build
 
 Install @tivio/sdk-react along with its peer dependencies
 ```sh
-npm i react@17 react-dom@17 @tivio/sdk-react
+npm i react@18 react-dom@18 @tivio/sdk-react
 # or
-yarn add react@17 react-dom@17 @tivio/sdk-react
+yarn add react@18 react-dom@18 @tivio/sdk-react
 ```
 
 ## Initialization
@@ -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'
+    }
+}
+```