palbase 0.10.1 → 0.11.0

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

@@ -34,11 +34,11 @@ export type Action = {
     /**
      * What it does.
      */
-    kind: "beta_review" | "export_compliance" | "expire_build";
+    kind: "beta_review" | "export_compliance" | "expire_build" | "apply_listing" | "submit_review" | "withdraw_review" | "release_version" | "phased_release";
     /**
-     * Its package.
+     * Its package (a TestFlight action).
      */
-    package_id: string;
+    package_id?: string;
     /**
      * What it does, exactly.
      */
@@ -56,13 +56,17 @@ export type Action = {
         [key: string]: unknown;
     };
     /**
-     * Where it is.
+     * Where it is: running is a confirmed one still being written (a page's screenshots).
      */
-    status: "planned" | "done" | "declined" | "failed";
+    status: "planned" | "running" | "done" | "declined" | "failed";
     /**
      * What it does, for the person who confirms it.
      */
     summary: string;
+    /**
+     * Its app (an App Store action).
+     */
+    app_id?: string;
 };
 /**
  * stores.action.changed: an action was planned, done, declined or failed.
@@ -79,7 +83,7 @@ export type ActionChangedEvent = {
     /**
      * Its package.
      */
-    package_id: string;
+    package_id?: string;
     /**
      * Where it is.
      */
@@ -88,6 +92,10 @@ export type ActionChangedEvent = {
      * What it does.
      */
     summary: string;
+    /**
+     * Its app (an App Store action).
+     */
+    app_id?: string;
 };
 /**
  * A page of actions, newest first.
@@ -183,6 +191,192 @@ export type AppPage = {
      */
     apps: App[];
 };
+/**
+ * What App Review is told of the version. The demo account's password is never read out.
+ */
+export type AppStoreReview = {
+    /**
+     * Whom App Review reaches.
+     */
+    contact_first_name: string;
+    /**
+     * Their last name.
+     */
+    contact_last_name: string;
+    /**
+     * Their email.
+     */
+    contact_email: string;
+    /**
+     * Their phone, with its country code.
+     */
+    contact_phone: string;
+    /**
+     * App Review signs in to review the app.
+     */
+    demo_account_required: boolean;
+    /**
+     * The account's user name.
+     */
+    demo_account_name: string;
+    /**
+     * Anything else App Review needs.
+     */
+    notes: string;
+    /**
+     * Apple holds the demo account's password.
+     */
+    has_demo_password: boolean;
+};
+/**
+ * What App Review is told; the demo account's password goes to Apple and is never kept or read out.
+ */
+export type AppStoreReviewRequest = {
+    /**
+     * Whom App Review reaches.
+     */
+    contact_first_name?: string;
+    /**
+     * Their last name.
+     */
+    contact_last_name?: string;
+    /**
+     * Their email.
+     */
+    contact_email?: string;
+    /**
+     * Their phone, with its country code.
+     */
+    contact_phone?: string;
+    /**
+     * App Review signs in to review the app.
+     */
+    demo_account_required?: boolean;
+    /**
+     * The account's user name.
+     */
+    demo_account_name?: string;
+    /**
+     * The account's password; left out, it stays as it is.
+     */
+    demo_account_password?: string | null;
+    /**
+     * Anything else App Review needs.
+     */
+    notes?: string;
+};
+/**
+ * The app's App Store version as App Review will see it, and what it would be refused for.
+ */
+export type AppStoreVersion = {
+    /**
+     * The app.
+     */
+    app_id: string;
+    version?: AppStoreVersionInfo;
+    review: AppStoreReview;
+    phased?: PhasedRelease;
+    /**
+     * The app has a price (free or paid).
+     */
+    priced: boolean;
+    /**
+     * The content rights statement (empty: not given).
+     */
+    content_rights: string;
+    /**
+     * What App Review would refuse the version for, each a line a person acts on; empty when it can be sent. App Privacy is answered in App Store Connect.
+     */
+    missing: string[];
+    watched?: WatchedVersion;
+    /**
+     * When a person said the app's privacy details were published in App Store Connect (app_privacy: published).
+     */
+    app_privacy_published_at?: string;
+};
+/**
+ * The App Store version's own fields.
+ */
+export type AppStoreVersionInfo = {
+    /**
+     * App Store Connect's id.
+     */
+    id: string;
+    /**
+     * The version (1.2.3).
+     */
+    version_string: string;
+    /**
+     * App Store Connect's state (PREPARE_FOR_SUBMISSION, WAITING_FOR_REVIEW, IN_REVIEW, PENDING_DEVELOPER_RELEASE, READY_FOR_DISTRIBUTION, REJECTED, DEVELOPER_REJECTED…).
+     */
+    state: string;
+    /**
+     * The version's copyright.
+     */
+    copyright: string;
+    /**
+     * When it goes out once approved: manual, after_approval or scheduled.
+     */
+    release: string;
+    /**
+     * A scheduled release's time.
+     */
+    release_at: string | null;
+    /**
+     * The attached build's number.
+     */
+    build_number: string;
+    /**
+     * The app's first version: it has no What's New.
+     */
+    first_version: boolean;
+};
+/**
+ * Prepares the version; a field left out stays as it is.
+ */
+export type AppStoreVersionRequest = {
+    /**
+     * Makes the version when the app has no editable one, or renames it (1.2.3).
+     */
+    version_string?: string | null;
+    /**
+     * The TestFlight build App Review gets (its version is the App Store version's).
+     */
+    build_number?: number | null;
+    /**
+     * The version's copyright (2026 Your Company).
+     */
+    copyright?: string | null;
+    /**
+     * When it goes out once approved.
+     */
+    release?: ("manual" | "after_approval" | "scheduled") | null;
+    /**
+     * A scheduled release's time.
+     */
+    release_at?: string | null;
+    /**
+     * Release it in phases over seven days.
+     */
+    phased?: boolean | null;
+    /**
+     * The content rights statement: the app shows, contains or reaches third-party content.
+     */
+    uses_third_party_content?: boolean | null;
+    /**
+     * free makes an app with no price free everywhere.
+     */
+    price?: "free" | null;
+    review?: AppStoreReviewRequest;
+    /**
+     * all: an app sold in no country or region is sold in every one, and in those Apple opens later; one sold somewhere keeps its countries (they are set in App Store Connect).
+     */
+    territories?: "all";
+    /**
+     * App Privacy has no API: published says the app's privacy details were published in App Store Connect, and the missing list stops asking for them; unpublished takes it back. Apple refusing a submission for App Privacy takes it back too.
+     */
+    app_privacy?: "published" | "unpublished";
+};
 /**
  * The project's Apple account (App Store Connect API key) as the API shows it: never the key itself.
  */
@@ -760,6 +954,179 @@ export type LinkAppRequest = {
      */
     name?: string;
 };
+/**
+ * An app's draft App Store page.
+ */
+export type Listing = {
+    /**
+     * The app.
+     */
+    app_id: string;
+    /**
+     * The draft's revision; 0 when there is none yet.
+     */
+    revision: number;
+    draft: ListingDraft;
+    /**
+     * Who wrote the revision.
+     */
+    updated_by: string | null;
+    /**
+     * When.
+     */
+    updated_at: string | null;
+};
+/**
+ * The app's App Store page as the project wants it.
+ */
+export type ListingDraft = {
+    /**
+     * An App Store category: UTILITIES, PRODUCTIVITY, GAMES…
+     */
+    primary_category?: string;
+    /**
+     * Another App Store category, or none.
+     */
+    secondary_category?: string;
+    /**
+     * The age rating questionnaire, Apple's questions and answers (NONE | INFREQUENT_OR_MILD | FREQUENT_OR_INTENSE, or true/false), written whole.
+     */
+    age_rating?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The page's languages, by App Store Connect's codes (en-US, tr, de-DE…).
+     */
+    locales: {
+        [key: string]: ListingLocale;
+    };
+};
+/**
+ * One language of the app's App Store page. A field left empty is not written.
+ */
+export type ListingLocale = {
+    /**
+     * The app's name in this language (2 to 30 characters).
+     */
+    name: string;
+    /**
+     * Under the name (30 characters at most).
+     */
+    subtitle?: string;
+    /**
+     * The privacy policy's address.
+     */
+    privacy_policy_url?: string;
+    /**
+     * What the app does (4000 characters at most).
+     */
+    description?: string;
+    /**
+     * Search keywords, comma-separated (100 bytes at most).
+     */
+    keywords?: string;
+    /**
+     * Above the description; changes without a new version (170 characters at most).
+     */
+    promotional_text?: string;
+    /**
+     * What's new in this version: an update's, never the first version's (4000 characters at most).
+     */
+    whats_new?: string;
+    /**
+     * The app's marketing page.
+     */
+    marketing_url?: string;
+    /**
+     * Where users get help.
+     */
+    support_url?: string;
+    /**
+     * Each display's screenshots, in order, by their SHA-256 (PUT /stores/apps/{app_id}/screenshots): iphone_6_9, iphone_6_5, ipad_13. 10 per display at most.
+     */
+    screenshots?: {
+        [key: string]: string[];
+    };
+};
+/**
+ * A page's plan: the steps, and the action that writes them once confirmed (none when nothing changes).
+ */
+export type ListingPlan = {
+    /**
+     * The draft's revision planned.
+     */
+    revision: number;
+    /**
+     * The App Store version the page belongs to.
+     */
+    version: string;
+    /**
+     * What changes, in the order written.
+     */
+    steps: ListingStep[];
+    action?: Action;
+};
+/**
+ * A draft saved over the revision it was edited from.
+ */
+export type ListingRequest = {
+    /**
+     * The revision it was edited from (0: the first).
+     */
+    revision: number;
+    draft: ListingDraft;
+};
+/**
+ * One change a page's plan makes at App Store Connect, with what it writes.
+ */
+export type ListingStep = {
+    /**
+     * What it changes.
+     */
+    kind: "categories" | "age_rating" | "app_info" | "version_text" | "screenshots";
+    /**
+     * Its language.
+     */
+    locale?: string;
+    /**
+     * Its screenshots' display.
+     */
+    display?: string;
+    /**
+     * The change, for the person who confirms it.
+     */
+    says: string;
+    /**
+     * The primary category written.
+     */
+    primary?: string;
+    /**
+     * The secondary category written.
+     */
+    secondary?: string;
+    /**
+     * The answers written.
+     */
+    age_rating?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The name, subtitle and privacy policy written.
+     */
+    info?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The version text written.
+     */
+    text?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The display's screenshots, in order.
+     */
+    shots?: PlannedShot[];
+};
 /**
  * A build handed to the stores.
  */
@@ -842,6 +1209,10 @@ export type PackageBundle = {
      * Its path in the app (empty for the app itself).
      */
     path: string;
+    /**
+     * The app's UIDeviceFamily: 1 the iPhone, 2 the iPad (App Review then asks for iPad screenshots).
+     */
+    device_families?: number[];
 };
 /**
  * stores.package.changed: a package was made, or its build arrived.
@@ -902,6 +1273,53 @@ export type PackageUpload = {
      */
     url: string;
 };
+/**
+ * A phased release: Apple's seven days (1, 2, 5, 10, 20, 50, 100%), started by the release, paused, resumed or completed.
+ */
+export type PhasedRelease = {
+    /**
+     * Where it is.
+     */
+    state: "INACTIVE" | "ACTIVE" | "PAUSED" | "COMPLETE";
+    /**
+     * When it started.
+     */
+    start_date?: string;
+    /**
+     * Its day (1 to 7).
+     */
+    day: number;
+    /**
+     * Days it has been paused (30 at most).
+     */
+    paused_days: number;
+};
+/**
+ * A phased release's next state.
+ */
+export type PhasedReleaseRequest = {
+    /**
+     * paused, active (resume) or complete (everyone gets it now).
+     */
+    state: "paused" | "active" | "complete";
+};
+/**
+ * A screenshot a step puts in a display, in its order.
+ */
+export type PlannedShot = {
+    /**
+     * The module's copy.
+     */
+    sha256: string;
+    /**
+     * How App Store Connect knows it.
+     */
+    md5: string;
+    /**
+     * What it is.
+     */
+    format: "png" | "jpeg";
+};
 /**
  * One thing the sandbox needs.
  */
@@ -1114,6 +1532,52 @@ export type SandboxTesterPage = {
      */
     testers: SandboxTester[];
 };
+/**
+ * A screenshot the module holds for an app's page.
+ */
+export type Screenshot = {
+    /**
+     * Its SHA-256: what the draft names it by.
+     */
+    sha256: string;
+    /**
+     * Bytes.
+     */
+    size: number;
+    /**
+     * Pixels.
+     */
+    width: number;
+    /**
+     * Pixels.
+     */
+    height: number;
+    /**
+     * png or jpeg.
+     */
+    format: "png" | "jpeg";
+    /**
+     * The displays it fits.
+     */
+    displays: string[];
+    /**
+     * When it was first sent.
+     */
+    created_at: string;
+};
+/**
+ * The PNG or JPEG image, 10 MB at most.
+ */
+export type ScreenshotFile = Blob;
+/**
+ * What goes to App Review with the version: its in-app purchases, by product id — a product's first review goes with an app version, as Apple requires. Each is READY_TO_SUBMIT at Apple, or the plan is refused (in_app_purchase_not_ready).
+ */
+export type SubmitRequest = {
+    /**
+     * The product ids of the subscriptions and in-app purchases sent with the version (50 at most).
+     */
+    in_app_purchases?: string[];
+};
 /**
  * A person to have in a group.
  */
@@ -1166,6 +1630,97 @@ export type UploadKey = {
      */
     fingerprint: string;
 };
+/**
+ * stores.version.changed: an app's App Store version came to a new state (sent to App Review, in review, approved, rejected, withdrawn, released).
+ */
+export type VersionChangedEvent = {
+    /**
+     * The app.
+     */
+    app_id: string;
+    /**
+     * Its bundle id.
+     */
+    bundle_id: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * The version.
+     */
+    version: string;
+    /**
+     * App Store Connect's id of it.
+     */
+    asc_version_id: string;
+    /**
+     * What it was; null when first seen.
+     */
+    previous_state: string | null;
+    /**
+     * What it is now.
+     */
+    state: string;
+    /**
+     * App Review's answer: approved, rejected; null when the state is none.
+     */
+    result: ("approved" | "rejected" | null) | null;
+};
+/**
+ * stores.version.reviewed: App Review approved or rejected a project's version. Sent to Palbase's own project, whose Studio tells the organization's owners.
+ */
+export type VersionReviewedEvent = {
+    /**
+     * The project (environment) the app is in.
+     */
+    project_id: string;
+    /**
+     * The app.
+     */
+    app_id: string;
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * Its bundle id.
+     */
+    bundle_id: string;
+    /**
+     * The version.
+     */
+    version: string;
+    /**
+     * App Store Connect's state.
+     */
+    state: string;
+    /**
+     * App Review's answer.
+     */
+    result: "approved" | "rejected";
+};
+/**
+ * The state the module last saw of the app's newest submitted version.
+ */
+export type WatchedVersion = {
+    /**
+     * The version.
+     */
+    version_string: string;
+    /**
+     * Its state.
+     */
+    state: string;
+    /**
+     * When it came to it.
+     */
+    state_at: string;
+    /**
+     * When it was last read.
+     */
+    checked_at: string;
+};
 /**
  * A build's note to testers.
  */
@@ -1213,6 +1768,14 @@ export interface Events {
      * stores.package.changed: a package was made, or its build arrived.
      */
     "stores.package.changed": PackageChangedEvent;
+    /**
+     * stores.version.changed: an app's App Store version came to a new state (sent to App Review, in review, approved, rejected, withdrawn, released).
+     */
+    "stores.version.changed": VersionChangedEvent;
+    /**
+     * stores.version.reviewed: App Review approved or rejected a project's version. Sent to Palbase's own project, whose Studio tells the organization's owners.
+     */
+    "stores.version.reviewed": VersionReviewedEvent;
 }
 /** Palbase Stores */
 export declare function client(t: Transport): {
@@ -1243,7 +1806,7 @@ export declare function client(t: Transport): {
     /**
      * Confirm an action
      *
-     * Runs a planned action: only a person's confirmation — Studio's call for its developer, signed in (it carries Studio's word for them, X-Palbase-Person) — only with its hash, only once, only before it expires. The project's secret key alone, an organization's access token or a CI job is refused (403 `person_required`), before the action is looked up. Emits `stores.action.changed`.
+     * Runs a planned action: only a person's confirmation — the developer's own call from Studio in their browser, with their Studio sign-in, which the edge verifies — only with its hash, only once, only before it expires. The project's secret key alone, an organization's access token or a CI job is refused (403 `person_required`), before the action is looked up. Emits `stores.action.changed`.
      */
     confirmAction(input: {
         path: {
@@ -1254,7 +1817,7 @@ export declare function client(t: Transport): {
         };
         body: ConfirmRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
-    }): Promise<Reply<200, Action>>;
+    }): Promise<Reply<200, Action> | Reply<202, Action>>;
     /**
      * Decline an action
      *
@@ -1416,6 +1979,46 @@ export declare function client(t: Transport): {
         body: LinkAppRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, App>>;
+    /**
+     * Read the draft App Store page
+     *
+     * The app's draft App Store page: what a plan compares with App Store Connect.
+     */
+    getListing(input: {
+        path: {
+            app_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, Listing>>;
+    /**
+     * Save the draft App Store page
+     *
+     * Saves the draft over the revision it was edited from; a draft that moved since is refused (409). Nothing is written to Apple: a plan is (POST …/listing/plan).
+     */
+    setListing(input: {
+        path: {
+            app_id: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: ListingRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Listing>>;
+    /**
+     * Plan the App Store page
+     *
+     * Compares the draft with what App Store Connect holds and plans the changes, language by language. Nothing is written until the plan is confirmed (POST /stores/actions/{id}/confirm with its hash); a confirmed plan runs after the answer (running, then done or failed).
+     */
+    planListing(input: {
+        path: {
+            app_id: 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<201, ListingPlan>>;
     /**
      * Make a package
      *
@@ -1431,6 +2034,25 @@ export declare function client(t: Transport): {
         body: CreatePackageRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, Package> | Reply<201, Package>>;
+    /**
+     * Upload a screenshot
+     *
+     * Takes one screenshot for the app's page (PNG or JPEG, 10 MB at most, an App Store size): kept by its SHA-256, which the draft names it by. The same image sent again is the one kept.
+     */
+    uploadScreenshot(input: {
+        path: {
+            app_id: string;
+        };
+        query?: {
+            for?: "page" | "review";
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: BodyInit;
+        contentType?: string; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Screenshot>>;
     /**
      * Read the app's test information
      *
@@ -1471,6 +2093,90 @@ export declare function client(t: Transport): {
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, UploadKey>>;
+    /**
+     * Read the App Store version
+     *
+     * The app's App Store version, its build, review details, phased release and price, and what App Review would refuse it for.
+     */
+    getAppStoreVersion(input: {
+        path: {
+            app_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, AppStoreVersion>>;
+    /**
+     * Prepare the App Store version
+     *
+     * Writes the version's fields, its build, how it is released, the review's details, the content rights statement and a free price — what can change until it is sent. Makes the version when the app has none that can change.
+     */
+    prepareAppStoreVersion(input: {
+        path: {
+            app_id: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: AppStoreVersionRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, AppStoreVersion>>;
+    /**
+     * Plan a phased release's next state
+     *
+     * Plans pausing, resuming or completing the version's phased release.
+     */
+    planPhasedRelease(input: {
+        path: {
+            app_id: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body: PhasedReleaseRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Action>>;
+    /**
+     * Plan releasing the approved version
+     *
+     * Plans releasing an approved version that waits for its developer. It cannot be taken back.
+     */
+    planReleaseVersion(input: {
+        path: {
+            app_id: 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<201, Action>>;
+    /**
+     * Plan sending the version to App Review
+     *
+     * Plans sending the version to App Review; refused (409 version_incomplete) with what is missing. Nothing is sent until the plan is confirmed.
+     */
+    planSubmitReview(input: {
+        path: {
+            app_id: string;
+        };
+        headers?: {
+            "Idempotency-Key"?: string;
+        };
+        body?: SubmitRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<201, Action>>;
+    /**
+     * Plan withdrawing the version from App Review
+     *
+     * Plans taking the version out of App Review: it is edited again, and sent again from the start.
+     */
+    planWithdrawReview(input: {
+        path: {
+            app_id: 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<201, Action>>;
     /**
      * Download a signed bundle with its link
      *