@pack/hydrogen 3.3.0 → 4.0.0

package/dist/index.d.ts

@@ -1,15 +1,51 @@
 import { PackClient } from '@pack/client';
 import { CacheCustom } from '@shopify/hydrogen';
 import { SessionStorage, Session, ActionFunctionArgs, LoaderFunctionArgs } from 'react-router';
-import * as react from 'react';
-import react__default, { Dispatch, SetStateAction, PropsWithChildren } from 'react';
+import * as React from 'react';
+import React__default, { Dispatch, SetStateAction, PropsWithChildren } from 'react';
+
+type ConsentState = "granted" | "denied" | "unknown";
+declare const CONSENT_PURPOSES: readonly ["analytics", "marketing", "preferences", "saleOfData"];
+type ConsentPurpose = (typeof CONSENT_PURPOSES)[number];
+/** The visitor's consent for each purpose, as resolved for one request. */
+type PackConsent = Record<ConsentPurpose, ConsentState>;
+/** Whether each purpose may be used, after the unknown-consent policy. */
+type PackConsentAllowed = Record<ConsentPurpose, boolean>;
+/** A consent update: `true`/`false` or an explicit state, per purpose. */
+type ConsentInput = Partial<Record<ConsentPurpose, boolean | ConsentState | null | undefined>>;
+/**
+ * Returns the visitor's consent from the theme's own consent tool (OneTrust,
+ * Cookiebot, ...). Return `undefined` for a purpose the tool has no answer for;
+ * the `__pack_user_consent` cookie is consulted next.
+ *
+ * Called on every request before anything renders, with no timeout: read the
+ * tool's own cookie from `request` rather than calling an API.
+ */
+type GetConsent = (request: Request) => ConsentInput | undefined | Promise<ConsentInput | undefined>;
+/**
+ * What an `unknown` purpose is treated as. `"granted"` keeps today's behaviour
+ * for visitors who have not answered a banner.
+ */
+type UnknownConsentPolicy = "granted" | "denied" | ((request: Request) => "granted" | "denied");
+interface ConsentOptions {
+    getConsent?: GetConsent;
+    unknownConsent?: UnknownConsentPolicy;
+}
 
 declare class PackSession {
     #private;
-    readonly id: string;
     readonly secret: string;
-    constructor(id: string, secret: string, sessionStorage: SessionStorage, session: Session);
-    static init(request: Request, secrets: string[]): Promise<PackSession>;
+    constructor(id: string, secret: string, sessionStorage: SessionStorage, session: Session, consent: PackConsent, unknownAs: "granted" | "denied");
+    static init(request: Request, secrets: string[], options?: ConsentOptions): Promise<PackSession>;
+    /**
+     * The visitor's session id. Persistent only with analytics consent; otherwise
+     * a fresh id on every request that is never written to the cookie.
+     */
+    get id(): string;
+    get consent(): PackConsent;
+    get consentAllowed(): PackConsentAllowed;
+    /** Replace the consent for the rest of this request, e.g. after `/pack/consent`. */
+    setConsent(consent: PackConsent): void;
     has(key: string): boolean;
     get(key: string): any;
     destroy(): Promise<string>;
@@ -17,6 +53,27 @@ declare class PackSession {
     commit(): Promise<string>;
 }
 
+/**
+ * What the theme tells us about who is signed in.
+ *
+ * `isLoggedIn` alone is enough for `auth_status`, and it is the cheap half: a
+ * session check rather than a Customer Account API query. Supply
+ * `shopifyCustomerId` only where the id itself is needed.
+ */
+interface CustomerContext {
+    isLoggedIn: boolean;
+    shopifyCustomerId?: string;
+}
+/**
+ * Asked only when an audience on this request could depend on who is signed
+ * in, at most once per request. Make it a local session read (Hydrogen's
+ * `customerAccount.isLoggedIn()`), not a Customer Account API query: it sits
+ * on the SSR critical path, bounded by `customerContextTimeoutMs`.
+ */
+type GetCustomerContext = (context: {
+    request: Request;
+}) => Promise<CustomerContext | undefined> | CustomerContext | undefined;
+
 interface TestInput {
     testId?: string;
     testHandle?: string;
@@ -34,16 +91,86 @@ interface Test$1 {
     impression?: {
         sectionIds?: string[];
     };
+    /**
+     * Set on a personalization, so the exposure ledger records it compactly. It
+     * is never stored in the session; see `getTestInfo`.
+     */
+    personalization?: true;
 }
 
+/**
+ * The sticky half of a bucketing decision — the only thing that has to survive
+ * between requests.
+ *
+ * `impressionTrigger` and `impression.sectionIds` are deliberately NOT stored.
+ * Every consumer of those two fields reads them off loader data produced from
+ * the freshly-fetched test rules in that same request (see
+ * `getImpressionSectionIdsForVariant`), so a stored copy is never read back — it
+ * is pure cookie weight, and it goes stale the moment the merchant edits the
+ * variant's sections.
+ */
+interface TestAssignment {
+    id: string;
+    handle: string;
+    testVariant: {
+        id: string;
+        handle: string;
+    };
+    assignedAt: number;
+}
+type TestAssignments = Record<string, TestAssignment>;
 declare class PackTestSession {
     #private;
     readonly id: string;
-    constructor(id: string, sessionStorage: SessionStorage, session: Session);
+    constructor(id: string, sessionStorage: SessionStorage, session: Session, isNewId?: boolean);
     static init(request: Request, secrets: string[]): Promise<PackTestSession>;
+    /**
+     * Keep a freshly generated id once a traffic draw has been made against it.
+     *
+     * A new id does not dirty the session on its own, so a visitor whose draw
+     * missed every test was never written, got a new id on the next request, and
+     * drew again until one hit. Called only after a draw rather than on creation,
+     * so visitors matching no test still get no cookie.
+     */
+    persistId(): void;
+    /**
+     * Every assignment on the session, keyed by test id.
+     *
+     * Normalizes and migrates on read, persisting only when the stored shape
+     * actually differs — a plain read of an already-clean session must not mark
+     * the session dirty, or `hasChanges()` would rewrite the cookie on every
+     * response.
+     */
+    getAssignments(): TestAssignments;
+    getAssignmentIds(): string[];
+    getAssignment(testId: string): TestAssignment | undefined;
+    hasAssignment(testId: string): boolean;
+    /**
+     * The session's stable primary — the oldest assignment, tie-broken by test id.
+     * Backs the single-test compatibility surface (`getTestData` -> `pack.abTest`),
+     * so it must not change as further tests are assigned during a visit.
+     */
+    getPrimaryAssignment(): TestAssignment | undefined;
+    /**
+     * Upsert one test's assignment. Returns false when the cap blocks a new
+     * assignment; updating a test already on the session always succeeds.
+     */
+    setAssignment(assignment: Omit<TestAssignment, "assignedAt"> & {
+        assignedAt?: number;
+    }): boolean;
+    clearAssignment(testId: string): void;
+    clearAllAssignments(): void;
+    /**
+     * @deprecated Reads only the primary assignment. Use `getAssignments()` —
+     * a session can hold one assignment per concurrently eligible test.
+     */
     getTestData(): Test$1 | undefined;
-    getExpireAt(): string | undefined;
+    /**
+     * @deprecated Upserts a single test. Use `setAssignment()` /
+     * `clearAllAssignments()`.
+     */
     setTestData(testData: Test$1 | undefined): void;
+    getExpireAt(): string | undefined;
     setExpireAt(expireAt: string | undefined): void;
     clearTestData(): void;
     hasTestData(): boolean;
@@ -85,6 +212,28 @@ interface CreatePackClientOptions extends EnvironmentOptions {
     i18n?: I18nOptions;
     /** Default theme data to use when no token is provided */
     defaultThemeData?: DefaultThemeData;
+    /**
+     * Who is signed in, for audiences that ask (`auth_status`). Called at most
+     * once per request, and only when an audience actually needs it.
+     *
+     * Return `{ isLoggedIn }` from a session check; add `shopifyCustomerId` only
+     * where the id itself is needed, since that costs a Customer Account API
+     * query. Omitting this option, throwing, or timing out all leave the answer
+     * UNKNOWN, and audiences that need it are refused rather than being served as
+     * if the visitor were a guest.
+     */
+    getCustomerContext?: GetCustomerContext;
+    /**
+     * Bound on `getCustomerContext`, in milliseconds. Defaults to 300 — enough for
+     * a session read or a healthy token refresh. Raise it only if expiry warnings
+     * show up; the hook sits on the SSR critical path, paid on any render where an
+     * audience could depend on who is signed in.
+     *
+     * If the hook throws or times out, the answer is unknown and those audiences
+     * are refused for that request: a visitor already seeing a signed-in
+     * personalization gets default content on that one render.
+     */
+    customerContextTimeoutMs?: number;
     /**
      * Initial request to extract query parameters from.
      * If not provided, it will be captured from the first handleRequest call.
@@ -107,7 +256,16 @@ interface QueryError {
 interface QueryResponse<T> {
     data: T | null;
     error: QueryError | null;
-    packTestInfo?: Test$1;
+    /**
+     * Tests newly assigned on this request, each owing one exposure.
+     *
+     * A list once a visitor can hold several tests. Deliberately the same key as
+     * the single-test era rather than a new one: themes forward this value to
+     * `PackTestRoute` without inspecting it, so widening it in place means an
+     * existing theme reports every exposure with no change. A lone test is still
+     * emitted unwrapped so anything that does read it keeps working.
+     */
+    packTestInfo?: Test$1 | Test$1[];
 }
 interface PackCustomizerMeta {
     environment?: string;
@@ -129,6 +287,8 @@ interface PackCustomizerMeta {
 }
 interface Pack {
     abTest: Test$1 | null | undefined;
+    /** Every test this visitor is bucketed into, including ones not serving here. */
+    abTests: Test$1[];
     /**
      * @deprecated The method should not be used
      */
@@ -136,6 +296,7 @@ interface Pack {
         storeId: string;
         sessionId: string;
         abTest: Test$1 | null | undefined;
+        abTests: Test$1[];
         isPreviewModeEnabled: boolean;
         customizerMeta: any;
     };
@@ -143,9 +304,16 @@ interface Pack {
         packStoreId: string;
         packSessionId: string;
         packAbTest: Test$1 | null | undefined;
+        packAbTests: Test$1[];
         packIsPreviewMode: boolean;
         packCustomizerMeta: PackCustomizerMeta | null;
+        packConsent: PackConsent;
+        packConsentAllowed: PackConsentAllowed;
     };
+    /** The visitor's consent per purpose, as resolved for this request. */
+    consent: PackConsent;
+    /** Whether each purpose may be used, after the unknown-consent policy. */
+    consentAllowed: PackConsentAllowed;
     handleRequest(request: Request): Promise<(response: Response) => void>;
     isPreviewModeEnabled: () => boolean;
     isValidEditToken: PackClient["isValidEditToken"];
@@ -162,16 +330,26 @@ declare function handleRequest(pack: Pack, request: Request, handleRequest: (req
 
 type UsePackCookiesOptions = {
     /**
-     * If set to `false`, Shopify cookies will be removed.
-     * If set to `true`, Shopify unique user token cookie will have cookie expiry of 1 year.
-     * Defaults to false.
+     * The visitor's analytics consent. When omitted, nothing is recorded.
      **/
     hasUserConsent?: boolean;
     /**
-     * The domain scope of the cookie. Defaults to empty string.
+     * @deprecated Ignored. `__pack_user_consent` is now set by the server for
+     * the storefront's own host.
      **/
     domain?: string;
 };
+/**
+ * Record the visitor's analytics consent in `__pack_user_consent`.
+ *
+ * @deprecated Use `setPackConsent()` from `@pack/react`, called when the
+ * visitor answers, which also covers marketing, preferences and sale of data.
+ * Themes using Shopify's privacy banner need neither: `PackProvider` forwards
+ * the banner's answer on its own.
+ *
+ * Posts only when `hasUserConsent` is given and differs from the recorded
+ * answer, so a stale value cannot overwrite the banner's on every page load.
+ */
 declare function usePackCookies(options?: UsePackCookiesOptions): void;
 
 /**
@@ -188,7 +366,7 @@ type PackTestImpressionSelector = string | string[] | ((packTestInfo: Test$1) =>
 type PackTestRouteProps = {
     impressionSelector?: PackTestImpressionSelector;
 };
-declare const PackTestRoute: ({ impressionSelector, }?: PackTestRouteProps) => null;
+declare const PackTestRoute: ({ impressionSelector, }?: PackTestRouteProps) => React__default.JSX.Element | null;
 
 interface Test {
     id: string;
@@ -212,35 +390,89 @@ type PackTestContextValue = {
     setPendingExposureQueue?: Dispatch<SetStateAction<Map<any, any>>>;
     exposedExperiments?: Set<unknown>;
 };
-declare const PackTestContext: react.Context<PackTestContextValue>;
+declare const PackTestContext: React.Context<PackTestContextValue>;
 declare const usePackTestContext: () => PackTestContextValue;
 
 interface PackContentProps {
     testExposureCallback?: (test: Test) => void;
+    /**
+     * Whether exposures may be reported. Defaults to the analytics consent the
+     * server resolved (`packConsentAllowed` from `getPackContextData()`), and to
+     * `false` when the root loader does not expose it.
+     */
     hasUserConsent?: boolean;
 }
-declare function PackTestProvider({ children, testExposureCallback, hasUserConsent, }: PropsWithChildren<PackContentProps>): react__default.JSX.Element;
+declare function PackTestProvider({ children, testExposureCallback, hasUserConsent: hasUserConsentProp, }: PropsWithChildren<PackContentProps>): React__default.JSX.Element;
 
-declare function useAbTest(): Test$1 | null;
+/**
+ * One test the visitor is bucketed into: given a handle, that specific test;
+ * argless, the oldest assignment.
+ *
+ * Argless is **not** necessarily the test supplying content on this page. While a
+ * visitor could hold only one test it was, so branching on `useAbTest()?.handle`
+ * to choose variant markup was safe; a visitor can now hold several. Pass a
+ * handle to name the test you mean, or use `useAbTests` for all of them.
+ *
+ * A handle matches on assignment, not on targeting: a test scoped to
+ * `/products/` is still returned on other pages, where its CMS content is not
+ * being served.
+ */
+declare function useAbTest(testHandle?: string): Test$1 | null;
+/**
+ * Every test the visitor is bucketed into, including ones whose targeting does
+ * not match the current page.
+ *
+ * Returns [] on a theme that has not adopted the plural context field, rather
+ * than throwing — `useAbTest` remains the compatibility surface.
+ */
+declare function useAbTests(): Test$1[];
 declare function useAbTestSessionId(): string;
-declare function useAbTestId(): string | undefined;
-declare function useAbTestHandle(): string | undefined;
-declare function useAbTestVariantId(): string | undefined;
-declare function useAbTestVariantHandle(): string | undefined;
+/**
+ * Each of these takes the same optional handle as `useAbTest`. Argless they read
+ * the visitor's oldest assignment, which is only the test you mean if they hold
+ * exactly one.
+ *
+ * `useAbTestVariantHandle` is the one that bites: new tests default to variants
+ * named `control` and `variant-b`, so unless renamed an argless read can return
+ * `"variant-b"` from one test while the test being branched on has the visitor in
+ * `control` — variant markup shown to a control-arm visitor. Pass the handle of
+ * the test being branched on.
+ */
+declare function useAbTestId(testHandle?: string): string | undefined;
+declare function useAbTestHandle(testHandle?: string): string | undefined;
+declare function useAbTestVariantId(testHandle?: string): string | undefined;
+declare function useAbTestVariantHandle(testHandle?: string): string | undefined;
 
 /**
  * The identity signals audience conditions evaluate against. Built once per SSR
  * request and passed to the resolver; every condition reads from this bundle
  * rather than re-parsing the request.
  *
- * Two population levels:
- *  - request-only (handleRequest / A/B): everything except customer identity;
- *  - request + customer (root loader / Personalization): also `shopifyCustomerId`.
- * All fields are optional; customer-keyed conditions simply don't match at the
- * request-only level.
+ * Every field is optional, and absence is not "no": a condition needing a
+ * signal that is missing is REFUSED by `unmetRequirements`, not evaluated
+ * against a default. Several conditions' documented fallback for a missing
+ * signal is to match — `auth_status: "anonymous"` matches precisely when no
+ * customer is known — so evaluating without one would serve to everybody.
+ *
+ * This used to describe two population levels, request-only for A/B in
+ * handleRequest and request-plus-customer for Personalization in the root
+ * loader. That split was never implemented: `handleRequest` performs no
+ * assignment, and both experiment types resolve in `getTestInfo` on the first
+ * CMS query of a request. The customer signal is therefore not a property of
+ * WHERE evaluation happens; it is supplied to it by the theme through
+ * `getCustomerContext`.
  */
 interface IdentityBundle {
     shopifyCustomerId?: string;
+    /**
+     * Tri-state: `undefined` means the theme did not tell us, and
+     * `unmetRequirements` refuses on it. Defaulting to `false` would make
+     * `auth_status: "anonymous"` match signed-in visitors too.
+     *
+     * Separate from `shopifyCustomerId`, which costs a Customer Account API query;
+     * `auth_status` only needs the boolean.
+     */
+    isLoggedIn?: boolean;
     ga4ClientId?: string;
     amplitudeDeviceId?: string;
     amplitudeUserId?: string;
@@ -262,8 +494,14 @@ interface IdentityBundle {
     referrer?: string;
 }
 interface BuildIdentityBundleOptions {
-    /** Shopify customer id, when resolved (loader-level / Personalization). */
+    /** Shopify customer id, when the theme supplied one. */
     shopifyCustomerId?: string;
+    /**
+     * Analytics consent as resolved for the Pack session (`getConsent`, the
+     * cookie, and the unknown-consent policy). Without it, only the cookie is
+     * read and an unanswered visitor counts as consented.
+     */
+    hasConsent?: boolean;
 }
 /**
  * Builds an IdentityBundle from an SSR request (headers + cookies) and, when
@@ -309,4 +547,4 @@ interface AudienceResolution {
  */
 declare function resolveRulesTree(rules: AudienceRulesTree | null | undefined, identity: IdentityBundle): Promise<AudienceResolution>;
 
-export { type AudienceResolution, type AudienceRuleNode, type AudienceRulesTree, type BuildIdentityBundleOptions, type ConditionEvaluator, type IdentityBundle, type MatchedCondition, type Pack, PackSession, PackTestContext, PackTestProvider, PackTestRoute, PackTestSession, type RuleConditionNode, type RuleGroupNode, type RuleGroupOperator, buildIdentityBundle, createPackClient, getConditionEvaluator, handleRequest, isConditionRegistered, action as previewModeAction, loader as previewModeLoader, registerConditionEvaluator, resolveRulesTree, useAbTest, useAbTestHandle, useAbTestId, useAbTestSessionId, useAbTestVariantHandle, useAbTestVariantId, usePackCookies, usePackTestContext };
+export { type AudienceResolution, type AudienceRuleNode, type AudienceRulesTree, type BuildIdentityBundleOptions, type ConditionEvaluator, type CustomerContext, type GetConsent, type GetCustomerContext, type IdentityBundle, type MatchedCondition, type Pack, type PackConsent, PackSession, PackTestContext, PackTestProvider, PackTestRoute, PackTestSession, type RuleConditionNode, type RuleGroupNode, type RuleGroupOperator, type TestAssignment, type TestAssignments, buildIdentityBundle, createPackClient, getConditionEvaluator, handleRequest, isConditionRegistered, action as previewModeAction, loader as previewModeLoader, registerConditionEvaluator, resolveRulesTree, useAbTest, useAbTestHandle, useAbTestId, useAbTestSessionId, useAbTestVariantHandle, useAbTestVariantId, useAbTests, usePackCookies, usePackTestContext };