@drip-apex/app-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,401 @@
-# Temporary Holding Version
+# Apex app SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@drip-apex/app-sdk` adds server-assigned flags, exposures, goals and purchases to
+hybrid apps built with Ionic, Angular, Capacitor or Cordova. It has zero runtime
+dependencies and uses WebView APIs: fetch, timers, Web Crypto, localStorage and
+visibility events. It does not change the DOM or load the storefront SDK.
+
+```sh
+npm install @drip-apex/app-sdk
+```
+
+For Cordova, allow the events host in your app's CSP **before testing**. Without
+`connect-src https://events.drip-apex.com`, every SDK request fails with a network
+error. Preserve any other origins your app needs:
+
+```html
+<meta http-equiv="Content-Security-Policy"
+      content="default-src 'self'; connect-src 'self' https://events.drip-apex.com">
+```
+
+Cordova iOS apps need `cordova-ios` 8+ to build with current Xcode. Older shells
+lack UIScene support and can crash at launch on current iOS; this is independent
+of Apex. When reinstalling the same SDK version, clear Angular's `.angular/cache`
+before rebuilding so the app loads the updated package.
+
+Configure once at app initialization. Create a **publishable** `apx_pk_…` key in
+Apex **Settings → Developers**. Never put a private API key or shop secret in the
+app. Await configure for storage hydration and the first assignment fetch to settle.
+`initTimeoutMs` (default 3,000 ms) bounds the wait for that fetch; initialization
+never rejects. Reads before resolution use defaults or cached assignments, with
+`variation(key).reason` reporting `default`, `cached`, or `stale` as appropriate.
+
+```ts
+import { Apex } from '@drip-apex/app-sdk';
+
+await Apex.configure({
+  publishableKey: 'apx_pk_live_…',
+  shopId: 'YOUR_SHOP_UUID',
+  applicationId: 'ch.coop.supercard',
+  appVersion: '1.0.0',
+  screen: () => 'home',
+  qaMode: false,
+});
+
+await Apex.identify('app-user-id'); // Wait for this user's assignments (or initTimeoutMs).
+const enabled = Apex.flag('welcome', false); // New user's value after a successful load.
+// Use await Apex.identify(null) on logout to restore the device UUID.
+await Apex.track('signup_completed');
+await Apex.trackPurchase('order-42', 42.5, 'CHF');
+```
+
+Attributes passed to `identify(userId, attributes)` are reserved for a future
+contract and are not sent in v1. `identify()` never rejects and resolves when the
+new identity's assignments load or `initTimeoutMs` elapses. Await it before reading
+flags for the new user. Reads before the matching assignments load return the
+previous user's values **without counting exposures**, including reads immediately
+after calling identify. `logExposure` is also deferred during this period; it does
+not replay an old assignment's exposure. Read the flag or call `logExposure` again
+after the new assignments load to count them normally. If the wait times out,
+previous values remain uncounted until a matching response succeeds. A later
+identify supersedes an earlier response. The identified user is persisted per
+shop/environment. On a cold launch, the SDK restores that user's cached
+assignments immediately, including their exposure and purchase attribution,
+before waiting for the network. Without a saved user it restores the anonymous
+device cache. `identify(null)` clears the saved user for the next launch. A new
+in-session identify still serves the previous assignments until its fetch succeeds.
+Purchases during this pending period keep the existing attribution rule: the base
+purchase uses the new current identity, while experiment copies use the previous
+served assignment and its identity. After the new assignments load, both use the
+new identity.
+
+## Angular service
+
+Provide one service at the root, configure through Angular app initialization,
+and inject that service into components. Change callbacks execute asynchronously;
+update Angular state through your usual change detection or signals.
+
+```ts
+import { Injectable, NgZone, inject, provideAppInitializer } from '@angular/core';
+import { Apex } from '@drip-apex/app-sdk';
+
+@Injectable({ providedIn: 'root' })
+export class ApexService {
+  private readonly zone = inject(NgZone);
+  init(): Promise<void> {
+    return this.zone.runOutsideAngular(() => Apex.configure({
+      publishableKey: 'apx_pk_live_…', shopId: 'YOUR_SHOP_UUID',
+      applicationId: 'ch.coop.supercard',
+      screen: () => 'home', // Replace with your router's route, excluding query/fragment.
+    }));
+  }
+  welcome() { return Apex.flag('welcome', false); }
+  subscribe(update: () => void) {
+    return Apex.onChange(change => {
+      if (change.type === 'changed') this.zone.run(update);
+    });
+  }
+}
+
+// Add this provider to ApplicationConfig.providers:
+export const apexInitializer = provideAppInitializer(() => inject(ApexService).init());
+
+// In a component:
+// private readonly experiments = inject(ApexService);
+// enabled = this.experiments.welcome();
+// private readonly subscription = this.experiments.subscribe(() => {
+//   this.enabled = this.experiments.welcome();
+// });
+// ngOnDestroy() { this.subscription.cancel(); }
+```
+
+For apps that react to `onChange`, start configuration in `NgZone.runOutsideAngular`
+so SDK timers and network completions do not trigger unnecessary change detection.
+Re-enter with `zone.run` only to update UI, as the service above does. Older Angular
+versions without `provideAppInitializer` can provide `APP_INITIALIZER` with
+`multi: true` and a factory that captures `const service = inject(ApexService)`
+synchronously and returns `() => service.init()`.
+
+## What your developers code
+
+- Read a flag where the app selects its content or code variant. Exposures are
+  automatic on compatible flag reads, deduped per experiment, variation and epoch
+  in a session. A missing epoch still exposes with `assignment_epoch: null`.
+- Call `track("goal_name")` once at each goal action. Custom events are
+  unattributed; purchase attribution is handled separately.
+- Call `trackPurchase(orderId, revenue, currency)` at order confirmation with a
+  stable order ID, a finite non-negative number in currency units and a
+  three-letter currency code. The SDK enqueues a base row plus one row for every
+  served assignment. These rows share an event ID and retain their IDs on retry.
+- Call `identify(userId)` on login and `identify(null)` on logout.
+- Set `qaMode: true` in test builds. Non-production environments are also QA.
+  Store builds use `environment: "production"` and `qaMode: false`.
+- After configure, use `Apex.deviceId` for an anonymous QA registration or event
+  lookup. After login use `Apex.userId`. Register that identity with the flag's
+  QA devices in Apex to pin a variation. Use the trusted-terminal tracking
+  verify endpoint described in the [wire contract](../../docs/mobile-sdk/wire-contract.md#check-a-test-builds-events)
+  to inspect recent events. During identify transitions, also check the previous
+  assignment identity. The app's publishable key cannot read management APIs.
+
+Content and configuration tests can use remote values. Layout and flow tests
+still require both versions in your app code behind the flag. Apex cannot remove
+that code from the app for you.
+
+## Typed objects and manual exposures
+
+```ts
+type Welcome = { title: string; button: { label: string; enabled: boolean } };
+const fallback: Welcome = { title: 'Welcome', button: { label: 'Start', enabled: false } };
+const validate = (v: unknown): v is Welcome => {
+  if (!v || typeof v !== 'object') return false;
+  const x = v as Partial<Welcome>;
+  return typeof x.title === 'string' && typeof x.button?.label === 'string'
+    && typeof x.button?.enabled === 'boolean';
+};
+const content = Apex.flagObject('welcome', fallback, { validate, exposure: 'manual' });
+// When the content is visible:
+Apex.logExposure('welcome');
+```
+
+A validator checks unknown JSON without throwing into app code. Without it,
+`flagObject` checks the outer JSON type only; TypeScript types do not validate
+nested fields at runtime. Returned values are copies. Unknown keys remain
+present. Assigned object reads expose only after successful validation. Failed or
+throwing validators return the default without exposure. This differs from the
+native typed getter. Missing assignments do not expose. Primitive reads require
+matching boolean/string/number types, finite numbers and safe integers; no string
+coercion. Missing or incompatible reads return the default and log once per key
+per session, only after an assignment set has loaded from cache or the network.
+Reads before that first load use defaults without warnings.
+`variation(key)` also exposes. A configured client returns a default variation
+with `reason: "default"` when unassigned; the unconfigured facade returns null.
+
+## Storage and lifecycle
+
+The default adapter uses localStorage. To use Capacitor Preferences, supply an
+adapter; Capacitor remains an app dependency, not an SDK dependency:
+
+```ts
+import { Preferences } from '@capacitor/preferences';
+import { Apex, type ApexStorage } from '@drip-apex/app-sdk';
+
+const storage: ApexStorage = {
+  async get(key) { return (await Preferences.get({ key })).value; },
+  async set(key, value) { await Preferences.set({ key, value }); },
+};
+await Apex.configure({ publishableKey: 'apx_pk_live_…', shopId: 'YOUR_SHOP_UUID', storage });
+```
+
+Adapters must atomically replace a string value or reject without changing it.
+The SDK stages queued events in memory and coalesces bursts into the latest queue
+snapshot, with at most one storage write in flight and one pending snapshot.
+`track()` and `trackPurchase()` wait for the write containing their events before
+resolving. A failed write restores the previous durable queue and logs the failure;
+purchase groups remain atomic. If an identify identity write fails, the SDK restores
+the previous in-memory identity, logs once that the identity could not be saved, and stops assignment
+fetches and event sends until a later identify successfully saves its identity.
+Queue/cache read failures log and use available defaults.
+
+Assignments refresh on configure, identify, explicit `refresh()`, and foreground
+transitions, matching the native SDKs. There is no periodic assignment polling;
+60 seconds is the cached assignment freshness window, not a network interval.
+Foreground refresh uses the configured jitter and respects retry deadlines.
+Startup schedules delivery of a hydrated nonempty queue on the first tick.
+Foreground transitions also flush a nonempty queue, respecting event retry deadlines.
+
+The SDK listens to browser `visibilitychange`, Cordova document `pause`/`resume`,
+and `globalThis.Capacitor?.Plugins?.App?.addListener('appStateChange', ...)` when
+available. It does not import or require a shell plugin. If your Capacitor version
+exposes App only as an imported module, forward its callback explicitly:
+
+```ts
+import { App } from '@capacitor/app';
+App.addListener('appStateChange', ({ isActive }) => {
+  Apex.setAppState(isActive ? 'foreground' : 'background');
+});
+// Or call Apex.setAppState('background' / 'foreground') from your own shell hooks.
+```
+
+Repeated state signals and rapid overlay transitions coalesce within one second.
+Backgrounding first completes any pending queue write, then flushes the persisted
+queue with best-effort fetch keepalive if the UTF-8 request body fits 64 KiB; larger batches use normal fetch. Disk remains
+authoritative until the server acknowledges a batch and the acknowledgement is
+persisted. Thirty continuous minutes in the background rotate the session and
+clear exposure/warning dedupe. Lifecycle listeners are removed on shutdown.
+Every cold launch creates a new session ID and allows a new exposure for each
+served assignment, even when relaunching within thirty minutes. This matches
+both native clients: iOS initializes `sessionId` with `UUID().uuidString` and
+Android with `UUID.randomUUID().toString()`; neither persists sessions across
+launches. The thirty-minute rule applies within a running client.
+
+`track`, `trackPurchase`, `refresh` and `flush` return promises for their local work,
+not server delivery. `identify` additionally waits for matching assignments or
+`initTimeoutMs`, without rejecting. `configure` resolves after storage hydration and
+the first assignment fetch settles (including failures), or its configurable
+3,000 ms fetch wait expires. A late response still updates flags. Use `onChange`
+to observe changed keys or a fatal stop (`{ type: "stopped", code }`). Subscriptions
+have an idempotent `cancel()`.
+To use a separate context, construct `new ApexClient(options)` and await its
+`ready` promise. Call `shutdown()` when retiring it. Do not run multiple clients
+with the same storage and shop/environment namespace simultaneously.
+
+## Delivery and options
+
+| Option | Default / limit |
+| --- | --- |
+| `environment` | `production` |
+| `qaMode` | `false`; other environments also stamp `qa_mode: true` |
+| `flushIntervalSeconds` | 5; clamped to 0.1–86,400 |
+| `batchSize` | 20; clamped to 1–20 |
+| `queueCapacity` | 2,000; clamped to 1–2,000 |
+| `queueRetentionHours` | 47; clamped to 0–47, below the 48-hour replay window |
+| `refreshJitterSeconds` | `[0, 10]` |
+| `initTimeoutMs` | 3,000; zero skips assignment waiting on configure and identify |
+| `platform` | Detected `ios`, `android`, or `web`; explicit override takes precedence |
+| `applicationId` / `appVersion` | `unknown` / empty string |
+| `screen` | `home`; an event's string `properties.screen` takes precedence |
+| `logger` | Optional; callback errors are isolated |
+| `fetch` / `baseUrl` | WebView fetch / `https://events.drip-apex.com` |
+
+Queue capacity evicts the oldest rows, dropping a whole older purchase group if
+the cut would split it. A new purchase larger than capacity or 200 rows is dropped
+whole with a diagnostic. Delivery keeps each purchase group in one request,
+expanding the batch target when needed within the 200-event server request limit.
+Expired rows are removed at enqueue/startup/flush. Future timestamps survive clock
+rollback. Events use `app://<lowercase applicationId>/<encoded screen path>` with
+no query or fragment. Platform detection uses Capacitor `getPlatform()`, then Cordova
+`device.platform` (case-insensitive), then iPhone/iPad/iPod or Android user-agent
+detection, finally `web`. Explicit `platform` overrides detection. The production
+Worker already accepts all three values; no Worker change is required.
+
+Fatal 401 codes `invalid_publishable_key` and `publishable_key_not_allowed` stop
+both network lanes while reads retain values. Retryable responses respect
+`Retry-After` seconds or HTTP dates. Missing lookup-unavailable retry headers
+use five seconds; ordinary 429 responses use exponential backoff with jitter.
+Other network/server failures use exponential 5/10/20/40/60-second
+backoff with 0–20% positive jitter, capped at 60 seconds. Unknown 401/403 use
+300 seconds; explicitly retryable assignment 4xx use 30 seconds. Other
+non-retryable assignment 4xx end that request without automatic retries. Event
+non-retryable 4xx drop the
+batch, except 401/403/408/429 which are retained. Only HTTP 202 with `ok: true`
+acknowledges events. A failed acknowledgement write retains the rows for replay.
+Requests time out after 30 seconds and refuse redirects.
+
+Supply `logger: line => ...` to receive developer diagnostics. Assignment fetch
+and event delivery failures report network errors or HTTP status, plus whether
+a retry is scheduled or the request/batch was dropped. Each lane and failure
+class (network error or distinct HTTP status) logs at most once per sixty seconds
+per client. Fatal auth logs its reason and that the SDK stopped; an obviously
+malformed publishable-key prefix also logs at configure. Keys, Authorization
+headers, response bodies and exception details are never included in these
+diagnostics. Without a logger the SDK emits no logs, including to the console.
+
+`track` rejects malformed revenue and property keys `email`, `phone`, `password`,
+`ssn`, `credit_card`, `card_number` (case/diacritic insensitive). Numeric revenue
+strings must match the Worker's strict decimal grammar, including comma decimals.
+Purchases strip caller order/revenue/currency aliases before adding explicit
+arguments. Properties must be JSON, including finite numbers.
+
+Authentication uses **only** `Authorization: Bearer <publishableKey>` on assignment
+and event requests. Cookie auth does not work from `capacitor://localhost`.
+The SDK never sends `X-Apex-Publishable-Key`; that header is not allowed by the
+production WebView CORS policy. No cookie credentials are needed.
+
+Importing or configuring the SDK during SSR is safe: it logs once per context,
+performs no storage/network work, and returns default flags. Configure again in
+the browser to activate it.
+
+Builds are ESM and CJS targeting ES2019, with declarations compatible with
+TypeScript 4.9+ and Angular 15+ webpack/esbuild builders, with no Node APIs in
+either runtime bundle. The package tests bundle consumers with esbuild, verify
+both declaration formats, and use offline TypeScript 4.9 when installed. If the
+4.9 check is skipped, the orchestrator must rerun the package tests with a locally
+available TypeScript 4.9 installation in node_modules before claiming that compiler
+was verified. Older Angular versions use `APP_INITIALIZER` as described above.
+Publishing is gated on main and npm trusted publishing; the repository
+owner must configure the `@drip-apex/app-sdk` trusted publisher for
+`publish-app-sdk.yml` in the `npm-production` environment before the first release.
+
+## Public failure contracts
+
+All instance and singleton methods contain invalid app input and app callback errors:
+no synchronous throw and no rejected SDK promise. Invalid input leaves identity,
+assignments, queue and lifecycle state unchanged. This is validation at the method
+boundary; a callback failure has its own recovery behavior below.
+
+| Method | Invalid input / failure outcome | Return |
+| --- | --- | --- |
+| `new ApexClient(options)`, `Apex.configure(options)` | Invalid options stop the new context before storage, listeners or network. One diagnostic through a callable logger. Reconfigure retires the previous context first. | `ready` / configure resolves `undefined` |
+| `identify(id, attributes?)` | Only nonempty string IDs up to 1,024 characters or `null` (anonymous) are accepted. Attributes, when supplied, must be a JSON record of strings up to 1,024 characters; they remain unused by evaluation. Invalid input logs and does not start a pending identity change. | Resolves `undefined` |
+| `flag(key, default, options?)` | Invalid key, primitive default or options returns the exact supplied default, without exposure. A missing or incompatible assignment warns once per key after assignments load. | Supplied default |
+| `flagObject(key, default, options?)` | Invalid key, JSON default or options returns the exact supplied default without exposure. Failed or throwing validators return the default, warn once per key, and never expose. Successful decoding isolates the returned value from cached data. | Supplied default |
+| `variation(key)` | Invalid key returns `null` without exposure. A valid missing key retains the existing `reason: 'default'` descriptor. Unsafe assigned JSON returns `null` with the typed warning. | `null` / default descriptor |
+| `logExposure(key)` | Invalid key is ignored without exposure. Pending identify suppresses all exposure entry points. | `undefined` |
+| `track(name, properties?)` | Nonempty names up to 256 characters; properties omitted/`undefined` mean `{}`. Non-record properties (including `null`, arrays and primitives), unsafe JSON, PII or invalid revenue log and drop before enqueue. | Resolves `undefined` |
+| `trackPurchase(id, revenue, currency, properties?)` | Nonempty string ID up to 1,024 characters, finite safe nonnegative revenue, three-letter currency after trimming/uppercasing. Properties have the same record contract as `track`. Invalid input logs and drops the whole purchase before enqueue. | Resolves `undefined` |
+| `onChange(handler)` | Nonfunctions log and return an inert subscription. A throwing handler logs; every other handler still runs. | `{ cancel() }`; cancel is idempotent |
+| `setAppState(state)` | Only `foreground` and `background` are accepted. Invalid input logs and leaves state/timers unchanged. | `undefined` |
+| `refresh()`, `flush()` | No arguments required; extra arguments ignored. Transport failure uses the documented lane retry policy; stopped contexts do nothing. | Resolves `undefined` |
+| `shutdown()` | Extra arguments ignored; stops networking and settles waiters, then waits for outstanding serialized storage work. | Resolves `undefined` |
+| `sdkVersion`, `deviceId`, `userId` | Read-only; no input or side effect. Singleton IDs are `undefined` before configure; instance IDs are empty before hydration. | String (or singleton `undefined`) |
+
+JSON input rejects cycles, nonfinite/unsafe integer numbers, functions, custom
+prototypes, accessors, and `__proto__`, `constructor`, or `prototype` keys at any
+level. Limits are 32 nesting levels, 10,000 visited nodes, 10,000 array slots
+(including sparse slots), and 1 MiB of combined
+UTF-16 string/key characters. Primitive flag defaults follow these limits too.
+Flag keys are nonempty strings up to 1,024 characters. Options are records with
+only the documented keys; callbacks must be functions, numeric options finite
+safe numbers, jitter a nonnegative ordered pair, and `baseUrl` an HTTP(S) URL
+without embedded credentials. Existing numeric option clamping still applies.
+
+Throwing loggers are isolated. Throwing `screen()` callbacks, unusable screen
+strings, or malformed Unicode screen paths fall back to `home`. Storage adapter
+get/set may throw synchronously or reject: device persistence failure stops
+initialization, cache read failure gives defaults, event write failure keeps the
+previous durable queue, acknowledgement write failure retains IDs for safe replay,
+and identity write failure uses the suspension/recovery contract above. A queue
+restored under a smaller capacity is activated only after successful trimming;
+if that write fails, the new context stops with disk untouched. Reconfigure
+after storage recovery to retry the restore. Atomic
+replace-or-reject is required of the adapter; an adapter that hangs forever can
+keep a storage operation (and shutdown) pending.
+
+Capacity and retention removals log their drop reasons with each coalesced write.
+Purchases larger than queue capacity or 200 rows are rejected whole with a diagnostic. A purchase group
+is delivered in one request: the batch target may expand to include its last
+whole group, without exceeding the server's 200-event request limit. Restored oversized
+legacy groups are dropped whole with a diagnostic. Event IDs intentionally match
+across the base and attributed purchase rows. Exactly-once server ingestion uses
+`(event_id, experiment_id, variation_id)` as its delivery key; network retry or
+failed local acknowledgement persistence can retransmit the same key.
+
+Long sessions bound warning keys at 256, diagnostic rate-limit keys at 128,
+listeners at 1,024, identity cache entries at four, and exposure dedupe keys at
+4,096 per session. Once the exposure bound is reached, new tuples are dropped
+with a diagnostic, preserving dedupe for tuples already counted.
+Session rotation clears exposure and typed-warning dedupe. At most three
+assignment requests remain outstanding (older requests are aborted on saturation),
+plus one event request; abort/timeout releases SDK bookkeeping even if a custom
+fetch ignores its signal. A non-aborted superseded fatal auth reply still stops
+both lanes.
+
+## Deterministic stress verification
+
+`npm test` includes 2,000 seeds × 200 operations (400,000 operations), input and
+assigned-value fuzzing, simulated process death with atomic disk survival, slow /
+failed persistence, unordered and abort-ignoring transports, and all lifecycle
+sources. Tracking-promise resolution and process death both check that resolved
+events remain on disk, delivered, or removed by a logged drop rule. Slow-adapter
+burst tests cover 500 and 2,000 events and require at most two writes, including
+bursts arriving during an existing write. Failures report the seed and operation.
+Replay one seed with
+`APEX_CHAOS_FIRST_SEED=424 APEX_CHAOS_SEEDS=424 npm test`; run a larger soak with
+`APEX_CHAOS_SEEDS=20000 APEX_CHAOS_OPERATIONS=1000 npm test`.
+
+The CI performance guard starts with a saturated 2,000-row durable backlog,
+then feeds 10,000 additional events through flush and atomic storage writes.
+It requires all 12,000 rows delivered within a generous 15-second wall-clock
+budget on the CI runner. This exercises the shipped 2,000-row capacity rather
+than allowing an impossible 10,000-row simultaneous queue. A separate 5,000-cycle
+session checks internal map/set, waiter, request and timer bounds.