palbase 0.16.1 → 0.17.1

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

@@ -45,6 +45,14 @@ export type DeliveryEvent = {
  * A device — never its token: a signed-in user's, or, with no one signed in on it, its installation's (user_id absent).
  */
 export type Device = {
+    /**
+     * The APNs environment an iOS token is for: the one its SDK said, or the one a push reached it through.
+     */
+    apns_environment?: "sandbox" | "production";
+    /**
+     * The project's app the device registered from: the one whose publishable key it presented. An iOS push goes to its bundle.
+     */
+    app_id?: string;
     app_version?: string;
     created_at: string;
     device_id: string;
@@ -80,6 +88,10 @@ export type DevicePage = {
  * A device's push token as the app's push SDK gave it: FCM's, APNs' (a PushKit VoIP token on ios_voip), Expo's (ExponentPushToken[…]), or a browser's push subscription (platform web: PushSubscription.toJSON(), its endpoint one of the browsers' push services). A token another device held moves here.
  */
 export type DeviceRegistration = {
+    /**
+     * The Apple Push Notification service environment an iOS token is for: sandbox (an app run from Xcode, a development-signed build) or production (TestFlight, the App Store, ad hoc). Palbase sends through it, to the bundle of the app whose publishable key registered the device. Absent: Palbase tries both and keeps the one that delivers.
+     */
+    apns_environment?: ("sandbox" | "production") | null;
     app_version?: string | null;
     /**
      * The app's own stable name for the device.
@@ -1957,6 +1969,14 @@ export type NotifyProvider = {
     active: boolean;
     channel: "email" | "sms" | "verify" | "whatsapp" | "push" | "iys";
     created_at: string;
+    /**
+     * Since when the provider's sends have failed for its own fault — its credential refused, a topic an APNs key may not send to: every send through it fails alike until it is fixed. A send to the app it failed for that goes through ends it, and so does saving it anew. Null while it works.
+     */
+    failing_since: string | null;
+    /**
+     * The provider's last such error (APNs error 403: InvalidProviderToken). Null while it works.
+     */
+    last_error: string | null;
     /**
      * Lower is tried first.
      */
@@ -1976,7 +1996,7 @@ export type NotifyProviderList = {
 export type NotifyProviderWrite = {
     active?: boolean;
     /**
-     * The provider's credentials, by channel. email — acs {connection_string, from_email}; ses {region, access_key_id, secret_access_key, from_domain}; sendgrid {api_key, from_domain, webhook_public_key: the signed Event Webhook's verification key, for delivery reports}; smtp {host, port, username, password, from_email, use_starttls}. sms — twilio {account_sid, auth_token or api_key_sid + api_key_secret, from_number or messaging_service_sid; with the auth token Twilio reports each text's delivery}; vonage {api_key, api_secret, from, signature_secret + signature_method (md5hash, md5, sha1, sha256, sha512) for its signed delivery receipts}; acs {connection_string, from_number}. verify — twilio_verify {account_sid, auth_token or api_key_sid + api_key_secret, service_sid}. whatsapp — meta {phone_number_id, access_token, api_version, app_secret + verify_token for its webhook}. push — fcm {the service account JSON}; apns {private_key, team_id, key_id, bundle_id, is_production}; expo {access_token}.
+     * The provider's credentials, by channel. email — acs {connection_string, from_email}; ses {region, access_key_id, secret_access_key, from_domain}; sendgrid {api_key, from_domain, webhook_public_key: the signed Event Webhook's verification key, for delivery reports}; smtp {host, port, username, password, from_email, use_starttls}. sms — twilio {account_sid, auth_token or api_key_sid + api_key_secret, from_number or messaging_service_sid; with the auth token Twilio reports each text's delivery}; vonage {api_key, api_secret, from, signature_secret + signature_method (md5hash, md5, sha1, sha256, sha512) for its signed delivery receipts}; acs {connection_string, from_number}. verify — twilio_verify {account_sid, auth_token or api_key_sid + api_key_secret, service_sid}. whatsapp — meta {phone_number_id, access_token, api_version, app_secret + verify_token for its webhook}. push — fcm {the service account JSON}; apns {private_key, team_id, key_id: a team-scoped APNs key, asked of Apple when saved; bundle_id and is_production optional — a push goes to the bundle of the app the device registered from, through the APNs environment it said}; expo {access_token}.
      */
     credentials: {
         [key: string]: unknown;
@@ -2095,11 +2115,40 @@ export type PushDelivery = {
     platform: string;
     provider: string;
     provider_message_id?: string;
+    /**
+     * Where an APNs push went: its environment and the app's bundle (production com.centauri).
+     */
+    route?: string;
     /**
      * The furthest it got.
      */
     status: "sent" | "failed" | "token_invalid" | "delivered" | "not_shown" | "dismissed" | "opened" | "action" | "unconfirmed";
 };
+/**
+ * notification.push_failing: a push provider that has started failing for its own fault.
+ */
+export type PushFailingEvent = {
+    /**
+     * push.
+     */
+    channel: string;
+    /**
+     * The provider's error (APNs error 403: InvalidProviderToken).
+     */
+    error: string;
+    /**
+     * When it started failing.
+     */
+    failing_since: string;
+    /**
+     * The project whose provider it is: the platform's own copy names the customer's.
+     */
+    project_id: string;
+    /**
+     * apns, fcm or expo.
+     */
+    provider: string;
+};
 /**
  * One report from the app about a push on this device.
  */
@@ -2685,6 +2734,10 @@ export interface Events {
      * notification.opened: the person opened a push.
      */
     "notification.opened": NotificationEvent;
+    /**
+     * notification.push_failing: a push provider has started failing for its own fault — its APNs key refused, a topic the key may not send to — and every push through it fails until its setting is fixed. Told to the project and to the platform's own (whose Studio mails the organization's owners), at most once a day a provider.
+     */
+    "notification.push_failing": PushFailingEvent;
     /**
      * notification.read: the recipient read it (WhatsApp).
      */

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

@@ -5937,6 +5937,314 @@ export type StoreID = {
      */
     product: string;
 };
+/**
+ * A customer support found, and what found them.
+ */
+export type CustomerMatch = {
+    /**
+     * The customer; null for a purchase made on the web by no one yet (its link not redeemed).
+     */
+    customer_id: string | null;
+    /**
+     * What found them: `customer_id`, an id a store gave the purchase or the buyer (`app_store`, `play_store`, `stripe`), or `email` (the address a buyer with no account gave at checkout).
+     */
+    matched_by: "customer_id" | "app_store" | "play_store" | "stripe" | "email";
+    /**
+     * The purchase found, when one was.
+     */
+    chain_id?: string;
+    /**
+     * The purchase's store.
+     */
+    store?: "app_store" | "play_store" | "stripe";
+    /**
+     * The purchase's product, as the catalog names it.
+     */
+    product?: string;
+    /**
+     * The purchase is the store's sandbox's.
+     */
+    is_sandbox: boolean;
+    /**
+     * When the customer was first seen, or the purchase made.
+     */
+    at: string;
+};
+/**
+ * The customers a query found, the newest first (at most 50).
+ */
+export type CustomerSearch = {
+    /**
+     * The query, trimmed.
+     */
+    query: string;
+    customers: CustomerMatch[];
+};
+/**
+ * A movement of a customer's credits.
+ */
+export type CreditMove = {
+    /**
+     * The credits' currency.
+     */
+    currency: string;
+    /**
+     * What moved them.
+     */
+    kind: "grant" | "revoke" | "unrevoke" | "expire" | "merge" | "forgive";
+    /**
+     * The change of the balance (negative: taken).
+     */
+    delta: number;
+};
+/**
+ * One thing that happened to a customer.
+ */
+export type CustomerEvent = {
+    /**
+     * When it happened, as the store or the module recorded it.
+     */
+    at: string;
+    /**
+     * What happened: a payment (`purchase`, `renewal`), a `refund`, a subscription's renewal turned off (`cancellation`) or back on (`resumption`), a failed charge (`billing_issue`), its end (`expiration`), a grant given (`grant`) or taken back (`grant_revoked`), credits moved (`credits`), a purchase moved to (`transfer_in`) or from (`transfer_out`) the customer.
+     */
+    kind: "purchase" | "renewal" | "refund" | "cancellation" | "resumption" | "billing_issue" | "expiration" | "grant" | "grant_revoked" | "credits" | "transfer_in" | "transfer_out";
+    /**
+     * The purchase's store.
+     */
+    store?: "app_store" | "play_store" | "stripe";
+    /**
+     * The product, as the catalog names it.
+     */
+    product?: string;
+    /**
+     * The product's plan, as the catalog names it.
+     */
+    plan?: string;
+    /**
+     * The store's id of the product.
+     */
+    store_product_id?: string;
+    /**
+     * The purchase is the store's sandbox's.
+     */
+    is_sandbox: boolean;
+    /**
+     * What was paid — a refund: what was given back —, as the store said it, in millionths of `currency`.
+     */
+    amount_micros?: number;
+    /**
+     * ISO 4217.
+     */
+    currency?: string;
+    /**
+     * The record's why: a refund's kind (`refund`, `chargeback`, `family`, `other`), a grant's or a credit movement's reason, how a purchase moved (`restore`, `merge`, `assign`, `purchase`).
+     */
+    reason?: string;
+    /**
+     * Who did it: `store` (the store, or the customer at it), `customer`, `project`, or the key or user that gave a grant or moved credits (`key:…`, `user:…`).
+     */
+    actor: string;
+    /**
+     * The purchase.
+     */
+    chain_id?: string;
+    /**
+     * The store's id of the transaction.
+     */
+    transaction_id?: string;
+    /**
+     * The grant.
+     */
+    grant_id?: string;
+    /**
+     * The grant's entitlement.
+     */
+    entitlement?: string;
+    credits?: CreditMove;
+    /**
+     * A transfer's other side: whom from, whom to (null: a purchase that was no one's).
+     */
+    other_customer_id?: string | null;
+};
+/**
+ * What happened to a customer, the newest first, a page at a time.
+ */
+export type CustomerHistory = {
+    /**
+     * The customer.
+     */
+    customer_id: string;
+    events: CustomerEvent[];
+    /**
+     * Goes on to the next page (send it as `cursor`); absent on the last page.
+     */
+    next_cursor?: string;
+};
+/**
+ * A grant as support reads it: active or not, and who took it back.
+ */
+export type GrantRecord = {
+    /**
+     * Its customer.
+     */
+    customer_id: string;
+    /**
+     * The entitlement.
+     */
+    entitlement: string;
+    /**
+     * When it ends; null for life.
+     */
+    expires_at: string | null;
+    /**
+     * Who gave it (the API key).
+     */
+    granted_by: string;
+    /**
+     * The grant's id.
+     */
+    id: string;
+    /**
+     * Why.
+     */
+    reason: string;
+    /**
+     * When it was revoked.
+     */
+    revoked_at: string | null;
+    /**
+     * When it started.
+     */
+    starts_at: string;
+    /**
+     * Who revoked it (the API key or user); null while it is not.
+     */
+    revoked_by: string | null;
+    /**
+     * Given now: started, not ended, not revoked.
+     */
+    active: boolean;
+};
+/**
+ * The grants given a customer, the newest first.
+ */
+export type CustomerGrants = {
+    /**
+     * The customer.
+     */
+    customer_id: string;
+    grants: GrantRecord[];
+};
+/**
+ * A revision of the catalog, as the list shows it.
+ */
+export type CatalogRevision = {
+    /**
+     * Its number.
+     */
+    revision: number;
+    /**
+     * When it was saved.
+     */
+    created_at: string;
+    /**
+     * Who saved it (the API key or user).
+     */
+    created_by: string;
+    /**
+     * The catalog is this revision now.
+     */
+    current: boolean;
+    /**
+     * How many products it defines.
+     */
+    products: number;
+    /**
+     * How many entitlements it defines.
+     */
+    entitlements: number;
+    /**
+     * How many credit currencies it defines.
+     */
+    currencies: number;
+    /**
+     * How many limits it defines.
+     */
+    limits: number;
+    /**
+     * How many offers it defines.
+     */
+    offers: number;
+    /**
+     * When a confirmed plan of it was last written to the stores; null for one never written.
+     */
+    applied_at: string | null;
+};
+/**
+ * The catalog's revisions, the newest first.
+ */
+export type CatalogRevisions = {
+    revisions: CatalogRevision[];
+    /**
+     * Goes on to the next page (send it as `cursor`); absent on the last page.
+     */
+    next_cursor?: string;
+};
+/**
+ * An entitlement, and the product that gives it with more of a limit.
+ */
+export type LimitUpgrade = {
+    /**
+     * The entitlement.
+     */
+    entitlement: string;
+    /**
+     * The entitlement's name, as the catalog gives it.
+     */
+    name: string;
+    /**
+     * The product that gives it.
+     */
+    product: string;
+    /**
+     * What the product gives of the limit in a window.
+     */
+    max: number;
+};
+/**
+ * The error envelope of a refused spend: with `limit_reached`, the limit and what would give the customer more of it.
+ */
+export type SpendRefusal = {
+    /**
+     * Machine-readable error code (snake_case)
+     */
+    error: string;
+    /**
+     * Human-readable explanation
+     */
+    error_description: string;
+    /**
+     * Correlation ID for log/audit lookup
+     */
+    request_id: string;
+    /**
+     * Seconds to wait before retrying; present on a refusal that ends with time.
+     */
+    retry_after?: number;
+    /**
+     * HTTP status code (mirrors the response status)
+     */
+    status: number;
+    /**
+     * With `limit_reached`: the limit.
+     */
+    limit?: string;
+    /**
+     * With `limit_reached`: the entitlements whose products give more of the limit than the customer has now, the smallest step up first (empty when none does) — for the app to offer.
+     */
+    upgrades?: LimitUpgrade[];
+};
 /** 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 {
     /**
@@ -6391,6 +6699,17 @@ export declare function client(t: Transport): {
         body: CreditForgiveRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, CreditForgiven>>;
+    /**
+     * List a customer's grants
+     *
+     * The grants given the customer, active, ended and revoked, the newest first (at most 500): a grant is revoked by the id read here (DELETE …/grants/{grant_id}).
+     */
+    listCustomerGrants(input: {
+        path: {
+            customer_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CustomerGrants>>;
     /**
      * Grant an entitlement
      *
@@ -7283,5 +7602,69 @@ export declare function client(t: Transport): {
         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>>;
+    /**
+     * Find customers
+     *
+     * Finds customers by what a person writing in has: their id; Apple's original transaction id or any transaction id of theirs; a Google order id (a renewal's `..N` or not); Stripe's subscription, payment intent, invoice or customer id; or the email address a buyer with no account gave at checkout, matched whole (case and spaces around it aside). The address is never kept: an HMAC of it is.
+     */
+    searchCustomers(input: {
+        query: {
+            q: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CustomerSearch>>;
+    /**
+     * Read a customer's history
+     *
+     * What happened to the customer, the newest first: their purchases' payments and refunds, their subscriptions' renewal turned off and on, failed charges and ends, the grants given and taken back (with their reason and by whom), the credits granted, taken back, expired and forgiven (spends are the credits' entries: GET …/credits/entries), and the purchases that moved to or from them.
+     */
+    getCustomerHistory(input: {
+        path: {
+            customer_id: string;
+        };
+        query?: {
+            cursor?: string; /** Events in a page (default 50). */
+            limit?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CustomerHistory>>;
+    /**
+     * List the catalog's revisions
+     *
+     * Every revision the catalog was saved as, the newest first: who saved it, when, what it defines, and when a confirmed plan of it was last written to the stores.
+     */
+    listCatalogRevisions(input?: {
+        query?: {
+            cursor?: string; /** Revisions in a page (default 50). */
+            limit?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CatalogRevisions>>;
+    /**
+     * Read a revision of the catalog
+     *
+     * The catalog as it was saved at that revision.
+     */
+    getCatalogRevision(input: {
+        path: {
+            revision: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, CatalogDoc>>;
+    /**
+     * Put an older revision back
+     *
+     * Saves the revision's catalog as the next revision, as an edit is: checked against the catalog's rules now (an older revision may break one added since: 422 `invalid_catalog`), what customers bought kept in it, If-Match the revision the catalog is now. Nothing is written to a store: a plan of it is made and confirmed (POST /purchases/catalog/plans). Emits `purchases.catalog.changed` with `restored_from`.
+     */
+    restoreCatalogRevision(input: {
+        path: {
+            revision: number;
+        };
+        headers: {
+            "If-Match": string; /** Makes the write safe to send again (at most 255 characters). A retry with the same key and the same request gets the first answer back, marked `Idempotent-Replayed: true`, and changes nothing; the same key with a different request is refused with 422, and while the first request still runs a retry gets 409 with Retry-After. Answers are kept for 24 hours. */
+            "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<200, CatalogDoc>>;
 };
 export type Client = ReturnType<typeof client>;