recur-tw 0.20.0 → 0.21.0

package/dist/checkout.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Type companion for "recur-tw/checkout" (dist/checkout.js).
+ *
+ * checkout.js is a side-effect auto-init script (Gumroad-style): it scans the
+ * page for `.recur-button` / data attributes and wires up the checkout dialog.
+ * It exports nothing — import it for its side effects only:
+ *
+ *   import 'recur-tw/checkout'
+ *
+ * (Copied into dist/ by the build script; see package.json "build".)
+ */
+export {};

package/dist/index.cjs

@@ -3249,7 +3249,7 @@ function toCamelCase(obj) {
 
 //#endregion
 //#region package.json
-var version = "0.20.0";
+var version = "0.21.0";
 
 //#endregion
 //#region src/context.tsx

package/dist/index.js

@@ -3224,7 +3224,7 @@ function toCamelCase(obj) {
 
 //#endregion
 //#region package.json
-var version = "0.20.0";
+var version = "0.21.0";
 
 //#endregion
 //#region src/context.tsx

package/dist/recur.umd.js

@@ -2245,7 +2245,7 @@ function ee(e,t){if(!w(e)||!e.hasOwnProperty(`raw`))throw Error(`invalid templat
         <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"/>
         <circle cx="12" cy="7" r="4"/>
       </svg>
-    `}setupEventListeners(){let e=this.shadowRoot?.querySelector(`button`);e&&e.addEventListener(`click`,this.handleClick)}redirectToPortal(e){let t=this.getAttribute(`target`);this.dispatchEvent(new CustomEvent(`portal-redirect`,{detail:{url:e},bubbles:!0,composed:!0})),t===`_blank`?window.open(e,`_blank`,`noopener,noreferrer`):window.location.href=e}async fetchAndRedirect(e){let t=this.getAttribute(`customer-id`),n=this.getAttribute(`return-url`);this._isLoading=!0,this.render(),this.setupEventListeners();try{let r={};t&&(r.customerId=t),n&&(r.returnUrl=n);let i=await fetch(e,{method:`POST`,headers:{"Content-Type":`application/json`},body:JSON.stringify(r)});if(!i.ok){let e=await i.json().catch(()=>({}));throw Error(e.error?.message||e.message||`HTTP ${i.status}: Failed to create portal session`)}let a=await i.json(),o=a.url||a.portalUrl;if(!o)throw Error(`Portal URL not found in response`);this._isLoading=!1,this.render(),this.setupEventListeners(),this.redirectToPortal(o)}catch(e){this._isLoading=!1,this.render(),this.setupEventListeners(),this.dispatchError(e instanceof Error?e.message:`Failed to create portal session`)}}dispatchError(e){console.error(`[recur-portal]`,e),this.dispatchEvent(new CustomEvent(`portal-error`,{detail:{message:e},bubbles:!0,composed:!0}))}},typeof window<`u`&&!customElements.get(`recur-portal`)&&customElements.define(`recur-portal`,nt)}));async function it(){if(typeof window>`u`){console.warn(`[Recur SDK] Cannot register Web Components: window is not defined`);return}await Promise.all([Promise.resolve().then(()=>(o(),i)),Promise.resolve().then(()=>(l(),s)),Promise.resolve().then(()=>(f(),u)),Promise.resolve().then(()=>(h(),p)),Promise.resolve().then(()=>(Se(),ye)),Promise.resolve().then(()=>(Ae(),Oe)),Promise.resolve().then(()=>(Le(),Pe)),Promise.resolve().then(()=>(Ze(),Ye)),Promise.resolve().then(()=>(et(),Qe)),Promise.resolve().then(()=>(rt(),tt))]);let e=[`recur-loading-spinner`,`recur-success-message`,`recur-error-display`,`recur-skeleton-loader`,`recur-payment-form-skeleton`,`recur-toast`,`recur-toast-container`,`recur-einvoice-section`,`recur-payment-form`,`recur-checkout`,`recur-portal`].filter(e=>!customElements.get(e));e.length>0&&console.warn(`[Recur SDK] The following components are not registered:`,e)}typeof window<`u`&&it();function at(e){return e.replace(/_([a-z])/g,(e,t)=>t.toUpperCase())}function X(e){if(e==null)return e;if(Array.isArray(e))return e.map(e=>X(e));if(e instanceof Date)return e;if(typeof e==`object`){let t={};for(let[n,r]of Object.entries(e)){let e=at(n);t[e]=X(r)}return t}return e}var ot=`0.20.0`;V();let st=ot;var ct=class{constructor(e){if(B(this,`config`,void 0),!e.publishableKey)throw Error(`publishableKey is required`);this.config={baseUrl:`https://api.recur.tw`,...e}}getHeaders(){return{"Content-Type":`application/json`,"X-Recur-Publishable-Key":this.config.publishableKey,"X-Recur-SDK-Type":`vanilla`,"X-Recur-SDK-Version":st,"X-Recur-Source":typeof window<`u`?window.location.origin:`server`}}async createSubscription(e){let{customerName:t,customerEmail:n}=e,r=e.productId||e.planId,i=e.productSlug;if(!r&&!i)throw Error(`Either productId or productSlug is required`);let a={customerName:t,customerEmail:n};r&&(a.productId=r),i&&(a.productSlug=i);let o=await fetch(`${this.config.baseUrl}/v1/subscriptions`,{method:`POST`,headers:this.getHeaders(),body:JSON.stringify(a)});if(!o.ok){let e=await o.json().catch(()=>({}));throw{code:e.error||`CHECKOUT_FAILED`,message:e.message||`Failed to initiate checkout`,details:e}}return X(await o.json())}async fetchProducts(e){let t=new URL(`${this.config.baseUrl}/v1/products`);e?.type&&t.searchParams.set(`type`,e.type);let n=await fetch(t.toString(),{method:`GET`,headers:this.getHeaders()});if(!n.ok){let e=await n.json().catch(()=>({}));throw{code:e.error||`FETCH_PRODUCTS_FAILED`,message:e.message||`Failed to fetch products`,details:e}}return X(await n.json())}async fetchPlans(){return{plans:(await this.fetchProducts({type:`SUBSCRIPTION`})).data}}getConfig(){return{...this.config}}};V();var lt=class{constructor(e,t){if(B(this,`config`,void 0),B(this,`options`,void 0),B(this,`container`,void 0),B(this,`checkoutId`,null),B(this,`sdkToken`,null),B(this,`sdkTimestamp`,null),B(this,`creditToken`,null),B(this,`sdkEnv`,`S`),B(this,`payuniSDK`,null),B(this,`isFormValid`,!1),this.config=e,this.options=t,typeof t.container==`string`){let e=document.querySelector(t.container);if(!e)throw Error(`Container not found: ${t.container}`);this.container=e}else this.container=t.container}async render(){try{await this.initCheckout(),this.renderHTML(),await this.loadPayUniSDK(),await this.initPayUniSDK(),this.setupFormSubmit()}catch(e){this.handleError(e)}}getBaseUrl(){if(this.config.baseUrl)return this.config.baseUrl;if(typeof window<`u`){let e=window.location.hostname;if(e===`localhost`||e.includes(`.test`)||e.includes(`.local`)||e===`127.0.0.1`)return`${window.location.protocol}//${window.location.host}/api`}return`https://api.recur.tw`}async initCheckout(){let e=this.getBaseUrl(),t=await fetch(`${e}/v1/checkouts`,{method:`POST`,headers:{"Content-Type":`application/json`,"X-Recur-Publishable-Key":this.config.publishableKey},body:JSON.stringify({productId:this.options.productId||this.options.planId,customerEmail:this.options.customerEmail,customerName:this.options.customerName})});if(!t.ok){let e=await t.json().catch(()=>({}));throw Error(e.error||`Failed to initialize checkout`)}let n=X(await t.json());this.checkoutId=n.checkout.id,this.sdkToken=n.sdkToken,this.sdkTimestamp=n.sdkTimestamp||null,this.creditToken=n.creditToken||null,this.sdkEnv=n.livemode?`P`:`S`}renderHTML(){this.container.innerHTML=`
+    `}setupEventListeners(){let e=this.shadowRoot?.querySelector(`button`);e&&e.addEventListener(`click`,this.handleClick)}redirectToPortal(e){let t=this.getAttribute(`target`);this.dispatchEvent(new CustomEvent(`portal-redirect`,{detail:{url:e},bubbles:!0,composed:!0})),t===`_blank`?window.open(e,`_blank`,`noopener,noreferrer`):window.location.href=e}async fetchAndRedirect(e){let t=this.getAttribute(`customer-id`),n=this.getAttribute(`return-url`);this._isLoading=!0,this.render(),this.setupEventListeners();try{let r={};t&&(r.customerId=t),n&&(r.returnUrl=n);let i=await fetch(e,{method:`POST`,headers:{"Content-Type":`application/json`},body:JSON.stringify(r)});if(!i.ok){let e=await i.json().catch(()=>({}));throw Error(e.error?.message||e.message||`HTTP ${i.status}: Failed to create portal session`)}let a=await i.json(),o=a.url||a.portalUrl;if(!o)throw Error(`Portal URL not found in response`);this._isLoading=!1,this.render(),this.setupEventListeners(),this.redirectToPortal(o)}catch(e){this._isLoading=!1,this.render(),this.setupEventListeners(),this.dispatchError(e instanceof Error?e.message:`Failed to create portal session`)}}dispatchError(e){console.error(`[recur-portal]`,e),this.dispatchEvent(new CustomEvent(`portal-error`,{detail:{message:e},bubbles:!0,composed:!0}))}},typeof window<`u`&&!customElements.get(`recur-portal`)&&customElements.define(`recur-portal`,nt)}));async function it(){if(typeof window>`u`){console.warn(`[Recur SDK] Cannot register Web Components: window is not defined`);return}await Promise.all([Promise.resolve().then(()=>(o(),i)),Promise.resolve().then(()=>(l(),s)),Promise.resolve().then(()=>(f(),u)),Promise.resolve().then(()=>(h(),p)),Promise.resolve().then(()=>(Se(),ye)),Promise.resolve().then(()=>(Ae(),Oe)),Promise.resolve().then(()=>(Le(),Pe)),Promise.resolve().then(()=>(Ze(),Ye)),Promise.resolve().then(()=>(et(),Qe)),Promise.resolve().then(()=>(rt(),tt))]);let e=[`recur-loading-spinner`,`recur-success-message`,`recur-error-display`,`recur-skeleton-loader`,`recur-payment-form-skeleton`,`recur-toast`,`recur-toast-container`,`recur-einvoice-section`,`recur-payment-form`,`recur-checkout`,`recur-portal`].filter(e=>!customElements.get(e));e.length>0&&console.warn(`[Recur SDK] The following components are not registered:`,e)}typeof window<`u`&&it();function at(e){return e.replace(/_([a-z])/g,(e,t)=>t.toUpperCase())}function X(e){if(e==null)return e;if(Array.isArray(e))return e.map(e=>X(e));if(e instanceof Date)return e;if(typeof e==`object`){let t={};for(let[n,r]of Object.entries(e)){let e=at(n);t[e]=X(r)}return t}return e}var ot=`0.21.0`;V();let st=ot;var ct=class{constructor(e){if(B(this,`config`,void 0),!e.publishableKey)throw Error(`publishableKey is required`);this.config={baseUrl:`https://api.recur.tw`,...e}}getHeaders(){return{"Content-Type":`application/json`,"X-Recur-Publishable-Key":this.config.publishableKey,"X-Recur-SDK-Type":`vanilla`,"X-Recur-SDK-Version":st,"X-Recur-Source":typeof window<`u`?window.location.origin:`server`}}async createSubscription(e){let{customerName:t,customerEmail:n}=e,r=e.productId||e.planId,i=e.productSlug;if(!r&&!i)throw Error(`Either productId or productSlug is required`);let a={customerName:t,customerEmail:n};r&&(a.productId=r),i&&(a.productSlug=i);let o=await fetch(`${this.config.baseUrl}/v1/subscriptions`,{method:`POST`,headers:this.getHeaders(),body:JSON.stringify(a)});if(!o.ok){let e=await o.json().catch(()=>({}));throw{code:e.error||`CHECKOUT_FAILED`,message:e.message||`Failed to initiate checkout`,details:e}}return X(await o.json())}async fetchProducts(e){let t=new URL(`${this.config.baseUrl}/v1/products`);e?.type&&t.searchParams.set(`type`,e.type);let n=await fetch(t.toString(),{method:`GET`,headers:this.getHeaders()});if(!n.ok){let e=await n.json().catch(()=>({}));throw{code:e.error||`FETCH_PRODUCTS_FAILED`,message:e.message||`Failed to fetch products`,details:e}}return X(await n.json())}async fetchPlans(){return{plans:(await this.fetchProducts({type:`SUBSCRIPTION`})).data}}getConfig(){return{...this.config}}};V();var lt=class{constructor(e,t){if(B(this,`config`,void 0),B(this,`options`,void 0),B(this,`container`,void 0),B(this,`checkoutId`,null),B(this,`sdkToken`,null),B(this,`sdkTimestamp`,null),B(this,`creditToken`,null),B(this,`sdkEnv`,`S`),B(this,`payuniSDK`,null),B(this,`isFormValid`,!1),this.config=e,this.options=t,typeof t.container==`string`){let e=document.querySelector(t.container);if(!e)throw Error(`Container not found: ${t.container}`);this.container=e}else this.container=t.container}async render(){try{await this.initCheckout(),this.renderHTML(),await this.loadPayUniSDK(),await this.initPayUniSDK(),this.setupFormSubmit()}catch(e){this.handleError(e)}}getBaseUrl(){if(this.config.baseUrl)return this.config.baseUrl;if(typeof window<`u`){let e=window.location.hostname;if(e===`localhost`||e.includes(`.test`)||e.includes(`.local`)||e===`127.0.0.1`)return`${window.location.protocol}//${window.location.host}/api`}return`https://api.recur.tw`}async initCheckout(){let e=this.getBaseUrl(),t=await fetch(`${e}/v1/checkouts`,{method:`POST`,headers:{"Content-Type":`application/json`,"X-Recur-Publishable-Key":this.config.publishableKey},body:JSON.stringify({productId:this.options.productId||this.options.planId,customerEmail:this.options.customerEmail,customerName:this.options.customerName})});if(!t.ok){let e=await t.json().catch(()=>({}));throw Error(e.error||`Failed to initialize checkout`)}let n=X(await t.json());this.checkoutId=n.checkout.id,this.sdkToken=n.sdkToken,this.sdkTimestamp=n.sdkTimestamp||null,this.creditToken=n.creditToken||null,this.sdkEnv=n.livemode?`P`:`S`}renderHTML(){this.container.innerHTML=`
       <div class="recur-embedded-checkout" style="max-width: 400px; margin: 0 auto; padding: 20px; font-family: system-ui, -apple-system, sans-serif;">
         <div class="recur-checkout-header" style="margin-bottom: 24px;">
           <h2 style="margin: 0 0 8px 0; font-size: 20px; font-weight: 600; color: #111;">Subscribe</h2>

package/dist/server.cjs

@@ -29,6 +29,94 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let node_crypto = require("node:crypto");
 node_crypto = __toESM(node_crypto, 1);
 
+//#region src/case-utils.ts
+/**
+* Case Conversion Utilities for SDK
+*
+* Converts API responses from snake_case to camelCase.
+* Our API uses snake_case for all external responses (REST convention),
+* but the SDK uses camelCase internally (TypeScript convention).
+*/
+/**
+* Convert a string from snake_case to camelCase
+* @example snakeToCamel('sdk_token') => 'sdkToken'
+* @example snakeToCamel('sdk_token_expires_at') => 'sdkTokenExpiresAt'
+*/
+function snakeToCamel(str) {
+	return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+* Recursively convert all keys in an object from snake_case to camelCase
+* Used for parsing API responses
+*/
+function toCamelCase(obj) {
+	if (obj === null || obj === void 0) return obj;
+	if (Array.isArray(obj)) return obj.map((item) => toCamelCase(item));
+	if (obj instanceof Date) return obj;
+	if (typeof obj === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(obj)) {
+			const camelKey = snakeToCamel(key);
+			result[camelKey] = toCamelCase(value);
+		}
+		return result;
+	}
+	return obj;
+}
+
+//#endregion
+//#region src/einvoice.ts
+/** 手機條碼: `/` + 7 chars from the MOF alphabet. */
+const MOBILE_BARCODE_RE = /^\/[0-9A-Z.+-]{7}$/;
+/** 統一編號: 8 digits. */
+const UBN_RE = /^\d{8}$/;
+/** 愛心碼: 3–7 digits. */
+const DONATION_CODE_RE = /^\d{3,7}$/;
+/**
+* 統一編號 checksum (post-2023 rule: weighted digit-sum divisible by 5, with
+* the 7-in-7th-digit alternate). Providers reject checksum-invalid UBNs at
+* issue time as a non-retryable failure, so the SDK catches this at entry.
+*/
+function isValidTaiwanUbn(ubn) {
+	if (!UBN_RE.test(ubn)) return false;
+	const weights = [
+		1,
+		2,
+		1,
+		2,
+		1,
+		2,
+		4,
+		1
+	];
+	let sum = 0;
+	for (let i = 0; i < 8; i++) {
+		const product = Number(ubn.charAt(i)) * (weights[i] ?? 0);
+		sum += Math.floor(product / 10) + product % 10;
+	}
+	if (sum % 5 === 0) return true;
+	return ubn.charAt(6) === "7" && (sum + 1) % 5 === 0;
+}
+/**
+* Validate buyer invoice preferences.
+*
+* @returns an error message, or `null` when the prefs are valid
+*/
+function validateEinvoicePrefs(prefs) {
+	if (typeof prefs !== "object" || prefs === null) return "Invalid einvoice prefs: expected an object like { type: \"personal\" }";
+	switch (prefs.type) {
+		case "personal": return null;
+		case "mobile_barcode": return MOBILE_BARCODE_RE.test(prefs.carrierCode) ? null : "Invalid einvoice mobile barcode: must be \"/\" followed by 7 characters (0-9, A-Z, ., +, -)";
+		case "ubn":
+			if (!isValidTaiwanUbn(prefs.ubn)) return "Invalid einvoice UBN (統一編號): must be 8 digits with a valid checksum";
+			if (!prefs.buyerName || !prefs.buyerName.trim() || prefs.buyerName.trim().length > 60) return "Invalid einvoice buyerName (公司抬頭): required, at most 60 characters";
+			return null;
+		case "donation": return DONATION_CODE_RE.test(prefs.donationCode) ? null : "Invalid einvoice donation code (愛心碼): must be 3-7 digits";
+		default: return `Invalid einvoice type: ${String(prefs.type)}`;
+	}
+}
+
+//#endregion
 //#region \0@oxc-project+runtime@0.140.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
@@ -140,7 +228,112 @@ var WebhookSignatureVerificationError = class extends Error {
 
 //#endregion
 //#region package.json
-var version = "0.20.0";
+var version = "0.21.0";
+
+//#endregion
+//#region src/server/resources/checkout-sessions.ts
+/**
+* Checkout Sessions Resource
+*
+* Create hosted checkout sessions server-side (Secret Key) and inspect their
+* status — the server-side counterpart of the client SDK's
+* createCheckoutSession/redirectToCheckout.
+*/
+const SDK_VERSION$3 = version;
+const SDK_TYPE$3 = "server";
+/** v1 error payloads carry { code, message } but no `type` — normalize so
+* RecurAPIError.type is always a string as its type claims. */
+function toRecurError(error, fallbackMessage) {
+	const e = error ?? {};
+	return {
+		type: e.type === "authentication_error" || e.type === "invalid_request_error" ? e.type : "api_error",
+		code: e.code ?? "unknown",
+		message: e.message ?? fallbackMessage,
+		doc_url: e.doc_url,
+		details: e.details
+	};
+}
+var CheckoutSessions = class {
+	constructor(config) {
+		_defineProperty(this, "config", void 0);
+		this.config = config;
+	}
+	headers() {
+		return {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${this.config.secretKey}`,
+			"X-Recur-SDK-Version": SDK_VERSION$3,
+			"X-Recur-SDK-Type": SDK_TYPE$3
+		};
+	}
+	/**
+	* Create a hosted checkout session and get the URL to redirect the buyer to.
+	*
+	* @example
+	* ```typescript
+	* const session = await recur.checkoutSessions.create({
+	*   productId: 'prod_xxx',
+	*   successUrl: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
+	*   cancelUrl: 'https://example.com/pricing',
+	*   externalCustomerId: 'user_123',
+	*   einvoice: { type: 'ubn', ubn: '04595252', buyerName: '恆吉股份有限公司' },
+	* });
+	* redirect(session.url);
+	* ```
+	*/
+	async create(params) {
+		if (!params.productId && !params.productSlug) throw new RecurAPIError({
+			type: "invalid_request_error",
+			code: "missing_product",
+			message: "Either productId or productSlug is required"
+		}, 400);
+		if (params.einvoice) {
+			const einvoiceError = validateEinvoicePrefs(params.einvoice);
+			if (einvoiceError) throw new RecurAPIError({
+				type: "invalid_request_error",
+				code: "invalid_einvoice",
+				message: einvoiceError
+			}, 400);
+		}
+		const body = {
+			successUrl: params.successUrl,
+			cancelUrl: params.cancelUrl
+		};
+		if (params.productId) body.productId = params.productId;
+		if (params.productSlug) body.productSlug = params.productSlug;
+		if (params.mode) body.mode = params.mode;
+		if (params.customerEmail) body.customerEmail = params.customerEmail;
+		if (params.customerName) body.customerName = params.customerName;
+		if (params.externalCustomerId) body.externalId = params.externalCustomerId;
+		if (params.metadata) body.metadata = params.metadata;
+		if (params.promotionCode) body.promotionCode = params.promotionCode;
+		if (params.collectPaymentMethod) body.collectPaymentMethod = params.collectPaymentMethod;
+		if (params.einvoice) body.einvoice = params.einvoice;
+		const baseUrl = this.config.baseUrl || "https://api.recur.tw";
+		const response = await fetch(`${baseUrl}/v1/checkout/sessions`, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify(body)
+		});
+		const data = await response.json();
+		if (!response.ok) throw new RecurAPIError(toRecurError(data.error, "Failed to create checkout session"), response.status);
+		return toCamelCase(data);
+	}
+	/**
+	* Retrieve a checkout session — e.g. to confirm status after the
+	* success-URL redirect.
+	*/
+	async retrieve(sessionId) {
+		const baseUrl = this.config.baseUrl || "https://api.recur.tw";
+		const response = await fetch(`${baseUrl}/v1/checkout/sessions/${encodeURIComponent(sessionId)}`, {
+			method: "GET",
+			headers: this.headers()
+		});
+		const data = await response.json();
+		if (!response.ok) throw new RecurAPIError(toRecurError(data.error, "Failed to retrieve checkout session"), response.status);
+		return toCamelCase(data);
+	}
+};
 
 //#endregion
 //#region src/server/resources/entitlements.ts
@@ -599,6 +792,7 @@ var Recur = class {
 	*/
 	constructor(secretKey, options) {
 		_defineProperty(this, "config", void 0);
+		_defineProperty(this, "checkoutSessions", void 0);
 		_defineProperty(this, "portal", void 0);
 		_defineProperty(this, "webhooks", void 0);
 		_defineProperty(this, "entitlements", void 0);
@@ -609,6 +803,7 @@ var Recur = class {
 			secretKey,
 			baseUrl: options?.baseUrl || "https://api.recur.tw"
 		};
+		this.checkoutSessions = new CheckoutSessions(this.config);
 		this.portal = new Portal(this.config);
 		this.webhooks = new Webhooks(this.config);
 		this.entitlements = new Entitlements(this.config);
@@ -617,6 +812,7 @@ var Recur = class {
 };
 
 //#endregion
+exports.CheckoutSessions = CheckoutSessions;
 exports.Recur = Recur;
 exports.RecurAPIError = RecurAPIError;
 exports.WEBHOOK_EVENT_TYPES = WEBHOOK_EVENT_TYPES;

package/dist/server.d.cts

@@ -1,3 +1,34 @@
+//#region src/einvoice.d.ts
+/**
+ * Taiwan e-invoice (電子發票) buyer preferences
+ *
+ * Mirrors the server's einvoicePrefsSchema (@workspace/einvoice). Validation is
+ * kept inline — no zod, no dependency on the einvoice packages — so the browser
+ * bundles stay lean. A contract test (__tests__/einvoice.test.ts) pins this
+ * implementation against the server schema and @paid-tw/einvoice's validators.
+ */
+/**
+ * Buyer invoice choice, collected at checkout when the merchant has an active
+ * e-invoice integration:
+ * - `personal`: 個人雲端發票, delivered via the buyer's email
+ * - `mobile_barcode`: 手機條碼載具, e.g. `/ABC1234`
+ * - `ubn`: 公司統編三聯式 (B2B), 8-digit 統一編號 + company title
+ * - `donation`: 捐贈發票 via 愛心碼
+ */
+type EinvoicePrefs = {
+  type: 'personal';
+} | {
+  type: 'mobile_barcode';
+  carrierCode: string;
+} | {
+  type: 'ubn';
+  ubn: string;
+  buyerName: string;
+} | {
+  type: 'donation';
+  donationCode: string;
+};
+//#endregion
 //#region src/server/types.d.ts
 /**
  * Recur Server SDK Types
@@ -251,6 +282,66 @@ interface EntitlementListResult {
    */
   entitlements: Entitlement[];
 }
+interface CheckoutSessionCreateParams {
+  /** Product ID — either productId or productSlug is required */
+  productId?: string;
+  /** Product slug — alternative to productId */
+  productSlug?: string;
+  /** PAYMENT (one-time), SUBSCRIPTION (recurring), or SETUP (save card); inferred from the product when omitted */
+  mode?: 'PAYMENT' | 'SUBSCRIPTION' | 'SETUP';
+  /** Redirect URL after successful payment (supports {CHECKOUT_SESSION_ID}) */
+  successUrl: string;
+  /** Redirect URL when the buyer cancels */
+  cancelUrl: string;
+  customerEmail?: string;
+  customerName?: string;
+  /** Your system's user ID — binds the resulting customer */
+  externalCustomerId?: string;
+  /** Arbitrary key-value data (Secret Key only) */
+  metadata?: Record<string, unknown>;
+  /** Pre-applied promotion code (validated at creation) */
+  promotionCode?: string;
+  /** 'always' (default) or 'if_required' (skip card collection at $0) */
+  collectPaymentMethod?: 'always' | 'if_required';
+  /** Taiwan e-invoice buyer preferences — prefills 發票資訊 on the hosted page */
+  einvoice?: EinvoicePrefs;
+}
+interface CheckoutSession {
+  id: string;
+  /** Hosted checkout URL to redirect the buyer to */
+  url: string;
+  expiresAt: string;
+  /** Effective amount after discount */
+  amount: number;
+  requiresPaymentMethod: boolean;
+  /** Client secret for status polling (pass to the client SDK if needed) */
+  clientSecret?: string;
+  /** Whether the organization issues e-invoices for paid checkouts */
+  einvoiceEnabled?: boolean;
+  livemode: boolean;
+}
+interface CheckoutSessionDetails {
+  id: string;
+  status: 'OPEN' | 'COMPLETE' | 'EXPIRED';
+  mode: 'PAYMENT' | 'SUBSCRIPTION' | 'SETUP';
+  customerEmail: string | null;
+  externalCustomerId: string | null;
+  orderId: string | null;
+  subscriptionId: string | null;
+  paymentIntentId: string | null;
+  setupIntentId: string | null;
+  amountTotal: number;
+  currency: string;
+  product: {
+    id: string;
+    name: string;
+    description?: string | null;
+  };
+  expiresAt: string;
+  createdAt: string;
+  completedAt: string | null;
+  livemode: boolean;
+}
 /**
  * All webhook event types Recur emits, as a runtime constant.
  *
@@ -339,6 +430,34 @@ declare class WebhookSignatureVerificationError extends Error {
   constructor(message: string);
 }
 //#endregion
+//#region src/server/resources/checkout-sessions.d.ts
+declare class CheckoutSessions {
+  private config;
+  constructor(config: RecurConfig);
+  private headers;
+  /**
+   * Create a hosted checkout session and get the URL to redirect the buyer to.
+   *
+   * @example
+   * ```typescript
+   * const session = await recur.checkoutSessions.create({
+   *   productId: 'prod_xxx',
+   *   successUrl: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
+   *   cancelUrl: 'https://example.com/pricing',
+   *   externalCustomerId: 'user_123',
+   *   einvoice: { type: 'ubn', ubn: '04595252', buyerName: '恆吉股份有限公司' },
+   * });
+   * redirect(session.url);
+   * ```
+   */
+  create(params: CheckoutSessionCreateParams): Promise<CheckoutSession>;
+  /**
+   * Retrieve a checkout session — e.g. to confirm status after the
+   * success-URL redirect.
+   */
+  retrieve(sessionId: string): Promise<CheckoutSessionDetails>;
+}
+//#endregion
 //#region src/server/resources/entitlements.d.ts
 /**
  * Entitlements resource for checking and listing customer entitlements
@@ -549,6 +668,20 @@ declare class Webhooks {
 //#region src/server/recur.d.ts
 declare class Recur {
   private config;
+  /**
+   * Checkout Sessions resource for hosted checkout (create + retrieve)
+   *
+   * @example
+   * ```typescript
+   * const session = await recur.checkoutSessions.create({
+   *   productId: 'prod_xxx',
+   *   successUrl: 'https://example.com/success',
+   *   cancelUrl: 'https://example.com/pricing',
+   * });
+   * redirect(session.url);
+   * ```
+   */
+  readonly checkoutSessions: CheckoutSessions;
   /**
    * Portal resource for managing customer portal sessions
    */
@@ -606,4 +739,4 @@ declare class Recur {
   constructor(secretKey: string, options?: Omit<RecurConfig, 'secretKey'>);
 }
 //#endregion
-export { type ApiErrorCode, type CustomerIdentifier, type DuplicateSubscriptionDetails, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError, WEBHOOK_EVENT_TYPES, type WebhookEvent, type WebhookEventType, WebhookSignatureVerificationError };
+export { type ApiErrorCode, type CheckoutSession, type CheckoutSessionCreateParams, type CheckoutSessionDetails, CheckoutSessions, type CustomerIdentifier, type DuplicateSubscriptionDetails, type EinvoicePrefs, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError, WEBHOOK_EVENT_TYPES, type WebhookEvent, type WebhookEventType, WebhookSignatureVerificationError };

package/dist/server.d.ts

@@ -1,3 +1,34 @@
+//#region src/einvoice.d.ts
+/**
+ * Taiwan e-invoice (電子發票) buyer preferences
+ *
+ * Mirrors the server's einvoicePrefsSchema (@workspace/einvoice). Validation is
+ * kept inline — no zod, no dependency on the einvoice packages — so the browser
+ * bundles stay lean. A contract test (__tests__/einvoice.test.ts) pins this
+ * implementation against the server schema and @paid-tw/einvoice's validators.
+ */
+/**
+ * Buyer invoice choice, collected at checkout when the merchant has an active
+ * e-invoice integration:
+ * - `personal`: 個人雲端發票, delivered via the buyer's email
+ * - `mobile_barcode`: 手機條碼載具, e.g. `/ABC1234`
+ * - `ubn`: 公司統編三聯式 (B2B), 8-digit 統一編號 + company title
+ * - `donation`: 捐贈發票 via 愛心碼
+ */
+type EinvoicePrefs = {
+  type: 'personal';
+} | {
+  type: 'mobile_barcode';
+  carrierCode: string;
+} | {
+  type: 'ubn';
+  ubn: string;
+  buyerName: string;
+} | {
+  type: 'donation';
+  donationCode: string;
+};
+//#endregion
 //#region src/server/types.d.ts
 /**
  * Recur Server SDK Types
@@ -251,6 +282,66 @@ interface EntitlementListResult {
    */
   entitlements: Entitlement[];
 }
+interface CheckoutSessionCreateParams {
+  /** Product ID — either productId or productSlug is required */
+  productId?: string;
+  /** Product slug — alternative to productId */
+  productSlug?: string;
+  /** PAYMENT (one-time), SUBSCRIPTION (recurring), or SETUP (save card); inferred from the product when omitted */
+  mode?: 'PAYMENT' | 'SUBSCRIPTION' | 'SETUP';
+  /** Redirect URL after successful payment (supports {CHECKOUT_SESSION_ID}) */
+  successUrl: string;
+  /** Redirect URL when the buyer cancels */
+  cancelUrl: string;
+  customerEmail?: string;
+  customerName?: string;
+  /** Your system's user ID — binds the resulting customer */
+  externalCustomerId?: string;
+  /** Arbitrary key-value data (Secret Key only) */
+  metadata?: Record<string, unknown>;
+  /** Pre-applied promotion code (validated at creation) */
+  promotionCode?: string;
+  /** 'always' (default) or 'if_required' (skip card collection at $0) */
+  collectPaymentMethod?: 'always' | 'if_required';
+  /** Taiwan e-invoice buyer preferences — prefills 發票資訊 on the hosted page */
+  einvoice?: EinvoicePrefs;
+}
+interface CheckoutSession {
+  id: string;
+  /** Hosted checkout URL to redirect the buyer to */
+  url: string;
+  expiresAt: string;
+  /** Effective amount after discount */
+  amount: number;
+  requiresPaymentMethod: boolean;
+  /** Client secret for status polling (pass to the client SDK if needed) */
+  clientSecret?: string;
+  /** Whether the organization issues e-invoices for paid checkouts */
+  einvoiceEnabled?: boolean;
+  livemode: boolean;
+}
+interface CheckoutSessionDetails {
+  id: string;
+  status: 'OPEN' | 'COMPLETE' | 'EXPIRED';
+  mode: 'PAYMENT' | 'SUBSCRIPTION' | 'SETUP';
+  customerEmail: string | null;
+  externalCustomerId: string | null;
+  orderId: string | null;
+  subscriptionId: string | null;
+  paymentIntentId: string | null;
+  setupIntentId: string | null;
+  amountTotal: number;
+  currency: string;
+  product: {
+    id: string;
+    name: string;
+    description?: string | null;
+  };
+  expiresAt: string;
+  createdAt: string;
+  completedAt: string | null;
+  livemode: boolean;
+}
 /**
  * All webhook event types Recur emits, as a runtime constant.
  *
@@ -339,6 +430,34 @@ declare class WebhookSignatureVerificationError extends Error {
   constructor(message: string);
 }
 //#endregion
+//#region src/server/resources/checkout-sessions.d.ts
+declare class CheckoutSessions {
+  private config;
+  constructor(config: RecurConfig);
+  private headers;
+  /**
+   * Create a hosted checkout session and get the URL to redirect the buyer to.
+   *
+   * @example
+   * ```typescript
+   * const session = await recur.checkoutSessions.create({
+   *   productId: 'prod_xxx',
+   *   successUrl: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
+   *   cancelUrl: 'https://example.com/pricing',
+   *   externalCustomerId: 'user_123',
+   *   einvoice: { type: 'ubn', ubn: '04595252', buyerName: '恆吉股份有限公司' },
+   * });
+   * redirect(session.url);
+   * ```
+   */
+  create(params: CheckoutSessionCreateParams): Promise<CheckoutSession>;
+  /**
+   * Retrieve a checkout session — e.g. to confirm status after the
+   * success-URL redirect.
+   */
+  retrieve(sessionId: string): Promise<CheckoutSessionDetails>;
+}
+//#endregion
 //#region src/server/resources/entitlements.d.ts
 /**
  * Entitlements resource for checking and listing customer entitlements
@@ -549,6 +668,20 @@ declare class Webhooks {
 //#region src/server/recur.d.ts
 declare class Recur {
   private config;
+  /**
+   * Checkout Sessions resource for hosted checkout (create + retrieve)
+   *
+   * @example
+   * ```typescript
+   * const session = await recur.checkoutSessions.create({
+   *   productId: 'prod_xxx',
+   *   successUrl: 'https://example.com/success',
+   *   cancelUrl: 'https://example.com/pricing',
+   * });
+   * redirect(session.url);
+   * ```
+   */
+  readonly checkoutSessions: CheckoutSessions;
   /**
    * Portal resource for managing customer portal sessions
    */
@@ -606,4 +739,4 @@ declare class Recur {
   constructor(secretKey: string, options?: Omit<RecurConfig, 'secretKey'>);
 }
 //#endregion
-export { type ApiErrorCode, type CustomerIdentifier, type DuplicateSubscriptionDetails, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError, WEBHOOK_EVENT_TYPES, type WebhookEvent, type WebhookEventType, WebhookSignatureVerificationError };
+export { type ApiErrorCode, type CheckoutSession, type CheckoutSessionCreateParams, type CheckoutSessionDetails, CheckoutSessions, type CustomerIdentifier, type DuplicateSubscriptionDetails, type EinvoicePrefs, type Entitlement, type EntitlementCheckOptions, type EntitlementCheckResult, type EntitlementListOptions, type EntitlementListResult, type EntitlementStatus, type EntitlementSubscription, type PortalSession, type PortalSessionCreateParams, Recur, RecurAPIError, type RecurConfig, type RecurError, WEBHOOK_EVENT_TYPES, type WebhookEvent, type WebhookEventType, WebhookSignatureVerificationError };