palbase 0.8.1 → 0.9.0

package/types/internal/src/modules/purchases.d.ts

@@ -431,6 +431,10 @@ export type Catalog = {
      * The products.
      */
     products: Product[];
+    /**
+     * Prices for a while, to whom the project chooses.
+     */
+    offers?: CatalogOffer[];
 };
 /**
  * purchases.catalog.applied: a plan's Stripe part was written (applied) or failed; or the stores module answered of its App Store or Google Play part.
@@ -1048,6 +1052,10 @@ export type CheckoutRequest = {
      */
     success_url: string;
     source?: CheckoutSource;
+    /**
+     * One of the catalog's offers the customer may take, on this plan: its coupon (or the promotion code of the coupon code that opened it), or its free trial, on the checkout.
+     */
+    offer?: string;
 };
 /**
  * What calling a leader takes — every variant seen by min_viewers subjects, the leader's chance to win min_chance — and what the results still lack, reason by reason: none, they are confident.
@@ -2456,6 +2464,10 @@ export type PaywallCondition = {
      * Locale.
      */
     locale?: string[];
+    /**
+     * Holds while the package's offer (its package component's offer) is the customer's to take: the package the component is in, else the selected one.
+     */
+    offer_open?: boolean;
     /**
      * Platform.
      */
@@ -2858,6 +2870,10 @@ export type PaywallPackage = {
      * Names the component, unique in the paywall: an app's code can draw its own part in its place.
      */
     id?: string;
+    /**
+     * One of the catalog's offers on the package: bought with it, and its texts' {{offer_price}} its price, while the customer may take it (GET /purchases/offers lists it).
+     */
+    offer?: string;
     /**
      * Plan.
      */
@@ -3164,7 +3180,7 @@ export type PaywallStop = {
     color: string;
 };
 /**
- * A text: the string itself, or `{"t": key}` of the language table. Either may hold variables the app fills from its store — `{{price}}`, `{{price_per_month}}`, `{{period}}`, `{{trial}}`, `{{savings}}`, `{{product_name}}` — of the package an item is, or of the selected package anywhere else. A text that names a variable its package has no value for (no trial, no savings) is not drawn.
+ * A text: the string itself, or `{"t": key}` of the language table. Either may hold variables the app fills from its store — `{{price}}`, `{{price_per_month}}`, `{{period}}`, `{{trial}}`, `{{savings}}`, `{{product_name}}`, `{{offer_price}}` (the price of the package's offer while the customer may take it, its price otherwise) — of the package an item is, or of the selected package anywhere else. A text that names a variable its package has no value for (no trial, no savings) is not drawn.
  */
 export type PaywallString = PaywallLiteral | PaywallTextKey;
 /**
@@ -3735,6 +3751,10 @@ export type PlacementPaywall = {
      * Its version; report it with the exposure.
      */
     version: number;
+    /**
+     * The offers the definition's packages are sold with that the signed-in customer may take now: what {{offer_price}} is the price of, and what such a package is bought with. None for no one signed in.
+     */
+    offers: OfferView[];
 };
 /**
  * What the placement shows the viewer at the moment, where it came from, and what each rule came to.
@@ -5264,30 +5284,538 @@ export type StripeAppInstall = {
     expires_at: string;
 };
 /**
- * An install started with its link's grant.
+ * An install started with its link's grant — or, with describe, only named.
  */
 export type StripeAppStartRequest = {
+    /**
+     * Name what the link connects, starting nothing: the grant is not spent, no cookie is set.
+     */
+    describe?: boolean;
     /**
      * The link's grant: `<project id>.<token>`, from its fragment.
      */
     grant: string;
 };
 /**
- * An install started: the project the account will be connected to, and Stripe's page to go on to.
+ * What an install link connects an account to — the project, its ref, in which mode — and, started, Stripe's page to go on to.
  */
 export type StripeAppStart = {
     /**
-     * The Palbase project's name.
+     * Stripe's install page, the install started: its state is the install's nonce, which the browser keeps. Absent when only described.
      */
-    project: string;
+    authorize_url?: string;
     /**
      * Live mode, or Stripe's test mode.
      */
     livemode: boolean;
     /**
-     * Stripe's install page: its state is the install's nonce, which the browser keeps.
+     * The Palbase project's name.
+     */
+    project: string;
+    /**
+     * The project's ref: its address's first label.
+     */
+    project_ref: string;
+};
+/**
+ * A percentage off a plan's price for a count of its billing periods.
+ */
+export type OfferDiscount = {
+    /**
+     * Percent off, 1 to 99.
+     */
+    percent: number;
+    /**
+     * Billing periods it lasts, 1 to 12.
+     */
+    periods: number;
+};
+/**
+ * An entitlement for a duration, with no store.
+ */
+export type OfferGrant = {
+    /**
+     * The catalog's entitlement.
+     */
+    entitlement: string;
+    /**
+     * How long, an ISO 8601 duration (P7D, P1M).
+     */
+    duration: string;
+};
+/**
+ * A price for a while, given to whom the project chooses — an analytics audience's members (who allowed personalization), or everyone — once a customer: a discount on some billing periods of a subscription's plans, a free trial of them, or an entitlement for a time with no store (a grant). One of discount, trial and grant. A discount or a trial is each store's own offer, written with the catalog: Apple's promotional offer, Google Play's developer-determined offer, a Stripe coupon; its key is its id at every store.
+ */
+export type CatalogOffer = {
+    /**
+     * Its key, and its id at the stores (hyphenated at Google Play).
+     */
+    key: string;
+    /**
+     * Its name (Apple's reference name), 1 to 64 characters.
+     */
+    name: string;
+    /**
+     * The subscription a discount or a trial is on.
+     */
+    product?: string;
+    /**
+     * Its plans; none, every plan.
+     */
+    plans?: string[];
+    discount?: OfferDiscount;
+    /**
+     * A free trial's length, an ISO 8601 duration.
+     */
+    trial?: string;
+    grant?: OfferGrant;
+    /**
+     * The analytics audience whose members are given it; none, everyone.
+     */
+    audience?: string;
+    /**
+     * When it is first given.
+     */
+    starts_at?: string;
+    /**
+     * When it is no longer given.
+     */
+    ends_at?: string;
+};
+/**
+ * An offer's promotional offer at the App Store.
+ */
+export type AppStoreOffer = {
+    /**
+     * Its identifier.
+     */
+    offer_id: string;
+    /**
+     * The subscriptions it is on.
+     */
+    product_ids: string[];
+};
+/**
+ * An offer's offer at Google Play: developer-determined, tagged palbase.
+ */
+export type PlayStoreOffer = {
+    /**
+     * Its id.
+     */
+    offer_id: string;
+    /**
+     * The subscription.
+     */
+    product_id: string;
+    /**
+     * The base plans it is on.
      */
-    authorize_url: string;
+    base_plan_ids: string[];
+};
+/**
+ * An offer on the web's checkout.
+ */
+export type WebOffer = {
+    /**
+     * The plans.
+     */
+    plans: string[];
+};
+/**
+ * An offer the customer may take now, with what each store sells it as.
+ */
+export type OfferView = {
+    /**
+     * The offer.
+     */
+    key: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * discount, trial or grant.
+     */
+    kind: "discount" | "trial" | "grant";
+    /**
+     * Its subscription.
+     */
+    product?: string;
+    /**
+     * Its plans.
+     */
+    plans?: string[];
+    discount?: OfferDiscount;
+    /**
+     * A free trial's length.
+     */
+    trial?: string;
+    grant?: OfferGrant;
+    /**
+     * When it ends.
+     */
+    ends_at?: string;
+    /**
+     * The coupon that opened it to the customer.
+     */
+    coupon?: string;
+    app_store?: AppStoreOffer;
+    play_store?: PlayStoreOffer;
+    web?: WebOffer;
+};
+/**
+ * The offers the signed-in customer may take now.
+ */
+export type Offers = {
+    /**
+     * Each.
+     */
+    offers: OfferView[];
+};
+/**
+ * Which subscription the signature is for, in which app, where StoreKit runs.
+ */
+export type AppleOfferRequest = {
+    /**
+     * The App Store product (one the offer is on).
+     */
+    product_id: string;
+    /**
+     * The app's bundle identifier (the connected app's is used when one is connected).
+     */
+    bundle_id?: string;
+    /**
+     * xcode for a StoreKit configuration on a developer's Mac (signed with its Subscription Offers Key); otherwise the App Store's.
+     */
+    environment?: string;
+};
+/**
+ * What StoreKit buys the promotional offer with, for this customer's purchases: Apple's subscription offer signature.
+ */
+export type AppleOfferSignature = {
+    /**
+     * The offer's identifier.
+     */
+    offer_id: string;
+    /**
+     * The subscription.
+     */
+    product_id: string;
+    /**
+     * The customer's appAccountToken: the purchase carries it.
+     */
+    app_account_token: string;
+    /**
+     * The key's id.
+     */
+    key_id: string;
+    /**
+     * Used once, lowercase.
+     */
+    nonce: string;
+    /**
+     * Milliseconds since 1970.
+     */
+    timestamp: number;
+    /**
+     * ES256, base64.
+     */
+    signature: string;
+};
+/**
+ * What came of an offer.
+ */
+export type OfferStats = {
+    /**
+     * The offer.
+     */
+    offer: string;
+    /**
+     * Customers shown it.
+     */
+    viewers: number;
+    /**
+     * Customers who took it.
+     */
+    redemptions: number;
+    /**
+     * Redemptions by store: app_store, play_store, stripe, promotional.
+     */
+    by_store: {
+        [key: string]: number;
+    };
+};
+/**
+ * Every offer of the catalog, counted.
+ */
+export type OfferStatsList = {
+    /**
+     * Each.
+     */
+    offers: OfferStats[];
+};
+/**
+ * A coupon to make: a code that opens one of the catalog's offers to whoever holds it, once a customer. palbase: Palbase takes the code; apple: an App Store offer code on one of the offer's plans, written to App Store Connect. One of code (shared) and one_time_codes.
+ */
+export type CouponRequest = {
+    /**
+     * Its key.
+     */
+    key: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * palbase or apple.
+     */
+    kind: "palbase" | "apple";
+    /**
+     * The offer it opens.
+     */
+    offer: string;
+    /**
+     * A code many share, 3 to 32 letters and digits.
+     */
+    code?: string;
+    /**
+     * How many times the shared code is taken.
+     */
+    max_redemptions?: number;
+    /**
+     * How many codes of one use each to make (1 to 25000).
+     */
+    one_time_codes?: number;
+    /**
+     * A guest cannot redeem it.
+     */
+    signed_in_only?: boolean;
+    /**
+     * When it ends (an App Store batch's codes must).
+     */
+    expires_at?: string;
+    /**
+     * An App Store offer code's plan of the offer's product.
+     */
+    plan?: string;
+};
+/**
+ * A coupon and what came of it.
+ */
+export type CouponInfo = {
+    /**
+     * Its key.
+     */
+    key: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * palbase or apple.
+     */
+    kind: string;
+    /**
+     * The offer it opens.
+     */
+    offer: string;
+    /**
+     * Its shared code.
+     */
+    code?: string;
+    /**
+     * The shared code's cap.
+     */
+    max_redemptions?: number | null;
+    /**
+     * Its batch's size.
+     */
+    one_time_codes?: number | null;
+    /**
+     * A guest cannot redeem it.
+     */
+    signed_in_only: boolean;
+    /**
+     * When it ends.
+     */
+    expires_at?: string | null;
+    /**
+     * What App Store Connect holds of an App Store offer code: product_id, state (pending, applied, failed), offer_code_id, error.
+     */
+    apple?: ({
+        [key: string]: unknown;
+    }) | null;
+    /**
+     * The web's Stripe promotion code of a shared code.
+     */
+    stripe_promotion_code?: string;
+    /**
+     * Times it was redeemed: the cap's count (a deleted user's redemption still spends it).
+     */
+    redemptions: number;
+    /**
+     * One-time codes given to people by messages.
+     */
+    codes_given: number;
+    /**
+     * When it was made.
+     */
+    created_at: string;
+    /**
+     * When it was revoked.
+     */
+    revoked_at?: string | null;
+};
+/**
+ * The project's coupons, newest first.
+ */
+export type CouponList = {
+    /**
+     * Each.
+     */
+    coupons: CouponInfo[];
+};
+/**
+ * A one-time code.
+ */
+export type CouponCode = {
+    /**
+     * The code.
+     */
+    code: string;
+    /**
+     * The user a message gave it to.
+     */
+    assigned_to: string | null;
+    /**
+     * When.
+     */
+    assigned_at: string | null;
+    /**
+     * The customer who redeemed it.
+     */
+    redeemed_by: string | null;
+    /**
+     * When.
+     */
+    redeemed_at: string | null;
+};
+/**
+ * A coupon's one-time codes.
+ */
+export type CouponCodes = {
+    /**
+     * Each.
+     */
+    codes: CouponCode[];
+};
+/**
+ * A code the customer typed.
+ */
+export type CouponRedeemRequest = {
+    /**
+     * The code, any case.
+     */
+    code: string;
+};
+/**
+ * What a code opened: the offer, and the grant when it gave one.
+ */
+export type Redeemed = {
+    /**
+     * The coupon.
+     */
+    coupon: string;
+    offer: OfferView;
+    grant?: GrantInfo;
+};
+/**
+ * The Subscription Offers Key of Xcode's StoreKit configuration.
+ */
+export type XcodeOfferKeyRequest = {
+    /**
+     * Its id.
+     */
+    key_id: string;
+    /**
+     * Its .p8 (PEM).
+     */
+    private_key: string;
+};
+/**
+ * The key kept.
+ */
+export type XcodeOfferKey = {
+    /**
+     * Its id.
+     */
+    key_id: string;
+};
+/**
+ * purchases.offer.redeemed.
+ */
+export type OfferRedeemedEvent = {
+    /**
+     * The customer.
+     */
+    customer_id: string;
+    /**
+     * The offer.
+     */
+    offer: string;
+    /**
+     * discount, trial or grant.
+     */
+    kind: string;
+    /**
+     * app_store, play_store, stripe, or promotional (a grant).
+     */
+    store: string;
+    /**
+     * What was bought.
+     */
+    product?: string;
+    /**
+     * Its plan.
+     */
+    plan?: string;
+    /**
+     * The purchase's chain.
+     */
+    chain_id?: string;
+    /**
+     * The coupon it was taken with.
+     */
+    coupon?: string;
+    /**
+     * A grant's entitlement.
+     */
+    entitlement?: string;
+};
+/**
+ * purchases.coupon.redeemed.
+ */
+export type CouponRedeemedEvent = {
+    /**
+     * The customer.
+     */
+    customer_id: string;
+    /**
+     * The coupon.
+     */
+    coupon: string;
+    /**
+     * The offer it opens.
+     */
+    offer?: string;
+    /**
+     * palbase or app_store.
+     */
+    store: string;
+    /**
+     * A one-time code.
+     */
+    one_time: boolean;
 };
 /** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
 export interface Events {
@@ -5355,6 +5883,14 @@ export interface Events {
      * purchases.subscription.changed: a customer's subscription started, renewed, stopped renewing (canceled) or renews again (uncanceled), could not be charged (billing_issue) or was again (recovered), ended (expired), or moved to another product (product_changed).
      */
     "purchases.subscription.changed": SubscriptionChangedEvent;
+    /**
+     * purchases.offer.redeemed: a customer took one of the catalog's offers — bought with it at a store, or given its grant — once.
+     */
+    "purchases.offer.redeemed": OfferRedeemedEvent;
+    /**
+     * purchases.coupon.redeemed: a customer redeemed a coupon — its code here, or an App Store offer code at Apple.
+     */
+    "purchases.coupon.redeemed": CouponRedeemedEvent;
 }
 /** Palbase Purchases */
 export declare function client(t: Transport): {
@@ -5657,7 +6193,7 @@ export declare function client(t: Transport): {
     /**
      * Start a Stripe App install
      *
-     * Starts an install with its link's grant, once: the grant is traded for the install's nonce, kept in the browser (an HttpOnly cookie of Palbase's address) and carried by Stripe (the state) — the way back is taken only in this browser, and the grant never reaches Stripe. Answers the project's name and Stripe's install page. A grant of no project, used, expired or started already: 410 `grant_invalid`, the same answer for each.
+     * Names what an install link's grant connects (describe), or starts the install with it, once: the grant is traded for the install's nonce, kept in the browser (an HttpOnly cookie of Palbase's address, the install's own) and carried by Stripe (the state) — the way back is taken once, only in this browser, and the grant never reaches Stripe. Answers the project's name and ref and, started, Stripe's install page. A grant of no project, used, expired or started already: 410 `grant_invalid`, the same answer for each.
      */
     startStripeAppInstall(input: {
         body: StripeAppStartRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
@@ -5666,7 +6202,7 @@ export declare function client(t: Transport): {
     /**
      * The Stripe App's return
      *
-     * Where Stripe sends a Stripe App's installer back, with the install's code and its state (the project and the install's nonce): taken only in the browser that started the install — its cookie is the nonce —, where the grant, tried once more, names the project; the code is traded at Stripe for the install's tokens, sealed under the project's key, and the account is the project's connection. A cancelled install (`error`) spends its grant; an account already connected through the App to another project is refused. Answers a page the installer reads. No credential: the grant and the browser's nonce are the authorization.
+     * Where Stripe sends a Stripe App's installer back, with the install's code and its state (the project and the install's nonce): taken once, only in the browser that started the install — its install's cookie is the nonce —, where the grant, spent now whatever comes of it, names the project; the code is traded at Stripe for the install's tokens, sealed under the project's key, and the account is the project's connection. A cancelled install (`error`) connects nothing; an account already connected through the App to another project is refused there (409), and that project keeps it with the tokens Stripe answered now. Answers a page the installer reads. No credential: the grant and the browser's nonce are the authorization.
      */
     completeStripeAppInstall(input?: {
         query?: {
@@ -6500,5 +7036,132 @@ export declare function client(t: Transport): {
         body: StripeEvent; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, undefined>>;
+    /**
+     * List my offers
+     *
+     * The offers the signed-in customer may take now: live, not taken before (once a customer), for everyone, for an audience they are in having allowed personalization, or opened to them by a coupon they redeemed — with what each store sells them as.
+     */
+    listMyOffers(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Offers>>;
+    /**
+     * Record an offer shown
+     *
+     * The app showed the offer to its customer: the first time is counted (GET /purchases/offers/stats).
+     */
+    recordOfferView(input: {
+        path: {
+            offer_key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Sign an App Store offer
+     *
+     * Apple's signature of the offer's promotional offer for the customer's purchase of one of its subscriptions: StoreKit buys it with these (Product.PurchaseOption.promotionalOffer). Signed with the connected In-App Purchase key — or, for a StoreKit configuration on a developer's Mac, its Subscription Offers Key (PUT /purchases/apple/xcode-offer-key). Apple gives a promotional offer to a customer who subscribes, or subscribed, in the group.
+     */
+    signAppleOffer(input: {
+        path: {
+            offer_key: string;
+        };
+        body: AppleOfferRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AppleOfferSignature>>;
+    /**
+     * Claim a grant offer
+     *
+     * Takes a grant offer: its entitlement for its duration, from now. Emits `purchases.offer.redeemed` and `purchases.entitlement.changed`.
+     */
+    claimOffer(input: {
+        path: {
+            offer_key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, GrantInfo>>;
+    /**
+     * Redeem a coupon code
+     *
+     * Redeems a code the customer typed, once a customer: a grant at once, a discount or a trial theirs to buy (GET /purchases/offers lists it with the coupon). A one-time code is anyone's once; a shared code up to its cap. Emits `purchases.coupon.redeemed` (and `purchases.offer.redeemed` for a grant).
+     */
+    redeemCoupon(input: {
+        body: CouponRedeemRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Redeemed>>;
+    /**
+     * Count the offers
+     *
+     * Every offer of the catalog, counted: customers shown it, customers who took it, by store.
+     */
+    getOfferStats(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, OfferStatsList>>;
+    /**
+     * List coupons
+     *
+     * The project's coupons, newest first, with what came of each.
+     */
+    listCoupons(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CouponList>>;
+    /**
+     * Create a coupon
+     *
+     * Makes a coupon: a code that opens one of the catalog's offers. A palbase coupon's one-time codes are made here; a shared code of a discount on the web is the Stripe promotion code of the offer's coupon too. An apple coupon is an App Store offer code App Store Connect makes (the stores module writes it; `apple.state` says how it went) — its one-time codes are given out as Palbase's are.
+     */
+    createCoupon(input: {
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: CouponRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, CouponInfo>>;
+    /**
+     * Get a coupon
+     *
+     * A coupon and what came of it.
+     */
+    getCoupon(input: {
+        path: {
+            coupon_key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CouponInfo>>;
+    /**
+     * Revoke a coupon
+     *
+     * Revokes a coupon: no code of it is redeemed from now; what was redeemed stays.
+     */
+    revokeCoupon(input: {
+        path: {
+            coupon_key: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * List a coupon’s codes
+     *
+     * A coupon's one-time codes: whom a message gave each to, who redeemed it. Accept: text/csv answers a file to hand out.
+     */
+    listCouponCodes(input: {
+        path: {
+            coupon_key: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CouponCodes>>;
+    /**
+     * Set Xcode’s offer key
+     *
+     * Keeps the Subscription Offers Key of Xcode's StoreKit configuration (Editor › Subscription Offers Key), sealed: an app run there buys a promotional offer with Palbase's signature. The Xcode certificate is set first.
+     */
+    setXcodeOfferKey(input: {
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: XcodeOfferKeyRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, XcodeOfferKey>>;
 };
 export type Client = ReturnType<typeof client>;