jg-sw 1.0.1 → 1.1.0

package/API.md

@@ -0,0 +1,576 @@
+# <a id="api-reference"></a>jg-sw API reference
+
+Every export of `jg-sw@1.1.0`, 26 in all, with its signature, its errors, and an example. It's generated from the package's TSDoc.
+
+## <a id="api-entry-main"></a>`jg-sw`
+
+- Functions: [`canInstallApp`](#api-canInstallApp), [`getServiceWorkerSnapshot`](#api-getServiceWorkerSnapshot), [`installApp`](#api-installApp), [`registerServiceWorker`](#api-registerServiceWorker), [`subscribeToServiceWorker`](#api-subscribeToServiceWorker), [`updateApp`](#api-updateApp)
+- Constants: [`DEFAULT_SERVICE_WORKER_PATH`](#api-DEFAULT_SERVICE_WORKER_PATH), [`DEFAULT_SERVICE_WORKER_SCOPE`](#api-DEFAULT_SERVICE_WORKER_SCOPE), [`ERRORS`](#api-ERRORS), [`REGISTRATION_DURATION_SECONDS`](#api-REGISTRATION_DURATION_SECONDS), [`SKIP_WAITING_MESSAGE_TYPE`](#api-SKIP_WAITING_MESSAGE_TYPE), [`UPDATE_INSTALL_TIMEOUT_SECONDS`](#api-UPDATE_INSTALL_TIMEOUT_SECONDS)
+- Interfaces: [`IBeforeInstallPromptEvent`](#api-IBeforeInstallPromptEvent)
+- Types: [`IAppInstallationState`](#api-IAppInstallationState), [`IInstallationPromptOutcome`](#api-IInstallationPromptOutcome), [`IRegisterServiceWorkerOptions`](#api-IRegisterServiceWorkerOptions), [`IServiceWorkerSnapshot`](#api-IServiceWorkerSnapshot), [`IUserChoice`](#api-IUserChoice)
+
+### <a id="api-functions"></a>Functions in `jg-sw`
+
+#### <a id="api-canInstallApp"></a>`canInstallApp`
+
+*Function*
+
+Checks whether installApp can show the installation prompt now: the browser offered one, and the page doesn't already run as the installed app. Only Chromium-based browsers offer it.
+
+```ts
+canInstallApp(): boolean
+```
+
+**Returns** `boolean`: Whether the app can be installed.
+
+**Example**
+
+```ts
+import { canInstallApp } from 'jg-sw';
+
+installButton.hidden = !canInstallApp();
+```
+
+#### <a id="api-getServiceWorkerSnapshot"></a>`getServiceWorkerSnapshot`
+
+*Function*
+
+Reads the service worker's state: its registration, its newest worker, whether an update waits, and whether the app can be installed. The same object comes back until something changes, so it can be passed to React's useSyncExternalStore, during server rendering too.
+
+```ts
+getServiceWorkerSnapshot(): IServiceWorkerSnapshot
+```
+
+**Returns** `IServiceWorkerSnapshot`: The snapshot.
+
+**Example**
+
+```ts
+import { getServiceWorkerSnapshot, subscribeToServiceWorker } from 'jg-sw';
+
+const { hasWaitingWorker, installation } = useSyncExternalStore(
+  subscribeToServiceWorker,
+  getServiceWorkerSnapshot,
+  getServiceWorkerSnapshot,
+);
+```
+
+#### <a id="api-installApp"></a>`installApp`
+
+*Function*
+
+Shows the browser's installation prompt and resolves to the user's answer, also kept in the snapshot as installation.promptOutcome. The browser offers each prompt once, so canInstallApp is false afterwards until it offers another.
+
+```ts
+installApp(): Promise<IInstallationPromptOutcome>
+```
+
+**Returns** `Promise<IInstallationPromptOutcome>`: A promise that resolves to 'accepted' or 'dismissed'.
+
+**Throws**
+
+- `NO_APP_INSTALLER`: The app can't be installed because the browser didn't offer the prompt.
+- `UNKNOWN_INSTALLATION_PROMPT_ERROR`: The installation prompt failed.
+
+**Example**
+
+```ts
+import { installApp } from 'jg-sw';
+
+installButton.addEventListener('click', async () => {
+  const outcome = await installApp(); // 'accepted' or 'dismissed'
+});
+```
+
+#### <a id="api-registerServiceWorker"></a>`registerServiceWorker`
+
+*Function*
+
+Registers the service worker and starts following its updates and whether the app can be installed. Later calls return the first call's promise. It never rejects: a failure lands in the snapshot's registrationError, an Exception with SW_NO_BROWSER_SUPPORT, EMPTY_SW_REGISTRATION, or SW_REGISTRATION_FAILED as its code, and the browser's error as its cause.
+
+```ts
+registerServiceWorker(
+  options?: IRegisterServiceWorkerOptions,
+): Promise<IServiceWorkerSnapshot>
+```
+
+**Parameters**
+
+- `options?` `IRegisterServiceWorkerOptions`: The worker's path and registration options, and whether to log. Defaults to `{}`.
+
+**Returns** `Promise<IServiceWorkerSnapshot>`: A promise that resolves to the snapshot once the registration settles.
+
+**Example**
+
+```ts
+import { hasErrorCode } from 'jg-exception';
+import { ERRORS, registerServiceWorker } from 'jg-sw';
+
+const { registration, registrationError } = await registerServiceWorker();
+if (hasErrorCode(registrationError, ERRORS.SW_NO_BROWSER_SUPPORT)) {
+  // the browser has no service workers
+}
+```
+
+#### <a id="api-subscribeToServiceWorker"></a>`subscribeToServiceWorker`
+
+*Function*
+
+Calls a listener whenever the snapshot changes, such as when an update finishes installing or the app becomes installable.
+
+```ts
+subscribeToServiceWorker(listener: () => void): () => void
+```
+
+**Parameters**
+
+- `listener` `() => void`: The function to call, without arguments; read the new state with getServiceWorkerSnapshot.
+
+**Returns** `() => void`: A function that stops the calls.
+
+**Example**
+
+```ts
+import { getServiceWorkerSnapshot, subscribeToServiceWorker } from 'jg-sw';
+
+const unsubscribe = subscribeToServiceWorker(() => {
+  if (getServiceWorkerSnapshot().hasWaitingWorker) {
+    showUpdateBanner();
+  }
+});
+```
+
+#### <a id="api-updateApp"></a>`updateApp`
+
+*Function*
+
+Updates the app to its newest version and reloads the page once, never in a loop. When a new version waits, it activates it and reloads once the new worker controls the page. Otherwise, it checks for one, waits up to UPDATE_INSTALL_TIMEOUT_SECONDS for it to install, then activates it the same way. When nothing new is found, the installation fails, or the time runs out, it reloads the page as it is.
+
+```ts
+updateApp(): Promise<void>
+```
+
+**Returns** `Promise<void>`: A promise that resolves once the new worker was asked to activate, or the page started reloading.
+
+**Example**
+
+```ts
+import { getServiceWorkerSnapshot, updateApp } from 'jg-sw';
+
+if (getServiceWorkerSnapshot().hasWaitingWorker) {
+  updateButton.addEventListener('click', () => updateApp());
+}
+```
+
+### <a id="api-constants"></a>Constants in `jg-sw`
+
+#### <a id="api-DEFAULT_SERVICE_WORKER_PATH"></a>`DEFAULT_SERVICE_WORKER_PATH`
+
+*Constant*
+
+the path the runtime registers the worker from, and the Vite plugin serves it at in development
+
+```ts
+const DEFAULT_SERVICE_WORKER_PATH: "/sw.js"
+```
+
+#### <a id="api-DEFAULT_SERVICE_WORKER_SCOPE"></a>`DEFAULT_SERVICE_WORKER_SCOPE`
+
+*Constant*
+
+the scope the runtime registers the worker with
+
+```ts
+const DEFAULT_SERVICE_WORKER_SCOPE: "/"
+```
+
+#### <a id="api-ERRORS"></a>`ERRORS`
+
+*Constant*
+
+the codes for every error thrown or reported by the runtime
+
+```ts
+const ERRORS: { SW_NO_BROWSER_SUPPORT: "SW_NO_BROWSER_SUPPORT"; EMPTY_SW_REGISTRATION: "EMPTY_SW_REGISTRATION"; SW_REGISTRATION_FAILED: "SW_REGISTRATION_FAILED"; NO_APP_INSTALLER: "NO_APP_INSTALLER"; UNKNOWN_INSTALLATION_PROMPT_ERROR: "UNKNOWN_INSTALLATION_PROMPT_ERROR" }
+```
+
+#### <a id="api-REGISTRATION_DURATION_SECONDS"></a>`REGISTRATION_DURATION_SECONDS`
+
+*Constant*
+
+the seconds a registration usually takes, for apps that wait before reading the snapshot
+
+```ts
+const REGISTRATION_DURATION_SECONDS: 5
+```
+
+#### <a id="api-SKIP_WAITING_MESSAGE_TYPE"></a>`SKIP_WAITING_MESSAGE_TYPE`
+
+*Constant*
+
+the type of the message the runtime posts to make a waiting worker activate
+
+```ts
+const SKIP_WAITING_MESSAGE_TYPE: "JG_SW_SKIP_WAITING"
+```
+
+#### <a id="api-UPDATE_INSTALL_TIMEOUT_SECONDS"></a>`UPDATE_INSTALL_TIMEOUT_SECONDS`
+
+*Constant*
+
+the seconds updateApp waits for a new worker to finish installing before it reloads anyway
+
+```ts
+const UPDATE_INSTALL_TIMEOUT_SECONDS: 30
+```
+
+### <a id="api-interfaces"></a>Interfaces in `jg-sw`
+
+#### <a id="api-IBeforeInstallPromptEvent"></a>`IBeforeInstallPromptEvent`
+
+*Interface*
+
+the event Chromium-based browsers fire when the app can be installed, which lets the app show the installation prompt when it chooses
+
+```ts
+interface IBeforeInstallPromptEvent extends Event {
+    readonly platforms: string[];
+    readonly userChoice: Promise<IUserChoice>;
+    prompt(): Promise<void>;
+}
+```
+
+**Members**
+
+- `platforms: string[]` (property): the platforms the event was dispatched for, such as 'web' or 'play'
+- `userChoice: Promise<IUserChoice>` (property): resolves to the user's answer once the prompt closes
+- `prompt(): Promise<void>` (method): shows the installation prompt
+
+### <a id="api-types"></a>Types in `jg-sw`
+
+#### <a id="api-IAppInstallationState"></a>`IAppInstallationState`
+
+*Type*
+
+whether the app can be installed, and what happened when it was offered
+
+```ts
+type IAppInstallationState = {
+    canInstall: boolean;
+    isAppInstalled: boolean | undefined;
+    isRunningInstalledApp: boolean;
+    promptOutcome: IInstallationPromptOutcome | undefined;
+};
+```
+
+**Members**
+
+- `canInstall: boolean` (property): whether installApp can show the installation prompt now
+- `isAppInstalled: boolean | undefined` (property): true once the browser reports the app was installed, undefined until then
+- `isRunningInstalledApp: boolean` (property): whether the page runs as the installed app, in a standalone window
+- `promptOutcome: IInstallationPromptOutcome | undefined` (property): the user's answer to the last prompt installApp showed, undefined until one is answered
+
+#### <a id="api-IInstallationPromptOutcome"></a>`IInstallationPromptOutcome`
+
+*Type*
+
+the action the user took on the installation prompt
+
+```ts
+type IInstallationPromptOutcome = 'accepted' | 'dismissed';
+```
+
+#### <a id="api-IRegisterServiceWorkerOptions"></a>`IRegisterServiceWorkerOptions`
+
+*Type*
+
+the options registerServiceWorker accepts
+
+```ts
+type IRegisterServiceWorkerOptions = {
+    path?: string;
+    options?: RegistrationOptions;
+    debugMode?: boolean;
+};
+```
+
+**Members**
+
+- `path: string` (property): the worker's script. Defaults to DEFAULT_SERVICE_WORKER_PATH, '/sw.js'
+- `options: RegistrationOptions` (property): the options passed to navigator.serviceWorker.register. Defaults to { scope: '/' }
+- `debugMode: boolean` (property): logs the registration, update, and installation events to the console
+
+#### <a id="api-IServiceWorkerSnapshot"></a>`IServiceWorkerSnapshot`
+
+*Type*
+
+the service worker's state. The object keeps its identity until something changes, so useSyncExternalStore(subscribeToServiceWorker, getServiceWorkerSnapshot) re-renders only on changes
+
+```ts
+type IServiceWorkerSnapshot = {
+    registration: ServiceWorkerRegistration | undefined;
+    worker: ServiceWorker | undefined;
+    registrationError: Exception | undefined;
+    hasWaitingWorker: boolean;
+    installation: IAppInstallationState;
+};
+```
+
+**Members**
+
+- `registration: ServiceWorkerRegistration | undefined` (property): the registration, once registerServiceWorker succeeds
+- `worker: ServiceWorker | undefined` (property): the newest worker: the installing one, else the waiting one, else the active one
+- `registrationError: Exception | undefined` (property): why the registration failed, with one of the ERRORS codes
+- `hasWaitingWorker: boolean` (property): whether a new version is installed and waits to activate, which updateApp does
+- `installation: IAppInstallationState` (property): whether the app can be installed, and what happened when it was offered
+
+#### <a id="api-IUserChoice"></a>`IUserChoice`
+
+*Type*
+
+the user's answer to the installation prompt
+
+```ts
+type IUserChoice = {
+    outcome: IInstallationPromptOutcome;
+    platform: string;
+};
+```
+
+**Members**
+
+- `outcome: IInstallationPromptOutcome` (property)
+- `platform: string` (property)
+
+## <a id="api-entry-build"></a>`jg-sw/build`
+
+- Functions: [`buildServiceWorker`](#api-build-buildServiceWorker), [`readServiceWorkerConfig`](#api-build-readServiceWorkerConfig), [`serviceWorkerPlugin`](#api-build-serviceWorkerPlugin), [`writeServiceWorker`](#api-build-writeServiceWorker)
+- Constants: [`ERRORS`](#api-build-ERRORS), [`ServiceWorkerConfigSchema`](#api-build-ServiceWorkerConfigSchema)
+- Types: [`IBuildServiceWorkerOptions`](#api-build-IBuildServiceWorkerOptions), [`IServiceWorkerConfig`](#api-build-IServiceWorkerConfig)
+
+### <a id="api-build-functions"></a>Functions in `jg-sw/build`
+
+#### <a id="api-build-buildServiceWorker"></a>`buildServiceWorker`
+
+*Function*
+
+Generates the service worker's source from a config, without writing it. Every generated worker gets a new cache name, `<cacheNamePrefix>--<10 random characters>`, so a new deployment replaces the previous one's cache when it activates.
+
+```ts
+buildServiceWorker(
+  config: { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string },
+  options?: IBuildServiceWorkerOptions,
+): Promise<string>
+```
+
+**Parameters**
+
+- `config` `{ outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string }`: The service worker config, as read by readServiceWorkerConfig or written inline.
+- `options?` `IBuildServiceWorkerOptions`: The environment the firebase-fcm template reads its Firebase config from, whether the worker caches (false for development), and the directory paths are resolved from. Defaults to `{}`.
+
+**Returns** `Promise<string>`: A promise that resolves to the worker's source.
+
+**Throws**
+
+- `FAILED_TO_READ_BASE_CONFIG`: The service worker config is invalid.
+- `INVALID_TEMPLATE_NAME`: The template must be 'base' or 'firebase-fcm'.
+- `INVALID_FIREBASE_SDK_VERSION`: The Firebase SDK version must be a version such as 12.4.0.
+- `INVALID_ENVIRONMENT`: The environment isn't supported, or the firebase-fcm template needs one.
+- `NOT_A_PATH_ELEMENT`: An asset to precache is outside outDir, or isn't a file or a directory.
+- `FAILED_TO_BUILD_CONFIG`: Unable to load the environment file.
+- `INVALID_FIREBASE_CONFIG`: The environment variable that holds the Firebase config is missing or
+- empty.
+- `FAILED_TO_READ_FIREBASE_CONFIG`: Unable to read the Firebase config from the environment
+- variable.
+
+**Example**
+
+```ts
+import { buildServiceWorker } from 'jg-sw/build';
+
+const source = await buildServiceWorker(
+  {
+    outDir: 'dist',
+    cacheNamePrefix: 'my-app',
+    template: 'base',
+    includeToPrecache: ['/', '/assets'],
+    excludeFilesFromPrecache: [],
+    excludeMIMETypesFromCache: ['application/json'],
+  },
+  { caching: true },
+);
+```
+
+#### <a id="api-build-readServiceWorkerConfig"></a>`readServiceWorkerConfig`
+
+*Function*
+
+Reads and validates a service worker config file, such as `jg-sw.config.json`.
+
+```ts
+readServiceWorkerConfig(
+  path: string,
+): Promise<{ outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string }>
+```
+
+**Parameters**
+
+- `path` `string`: The config file's path.
+
+**Returns** `Promise<{ outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string }>`: A promise that resolves to the config.
+
+**Throws**
+
+- `FAILED_TO_READ_BASE_CONFIG`: Unable to read the service worker config, or it is invalid.
+- `INVALID_TEMPLATE_NAME`: The template must be 'base' or 'firebase-fcm'.
+- `INVALID_FIREBASE_SDK_VERSION`: The Firebase SDK version must be a version such as 12.4.0.
+
+**Example**
+
+```ts
+import { readServiceWorkerConfig } from 'jg-sw/build';
+
+const config = await readServiceWorkerConfig('jg-sw.config.json');
+config.template; // 'base'
+```
+
+#### <a id="api-build-serviceWorkerPlugin"></a>`serviceWorkerPlugin`
+
+*Function*
+
+Creates a Vite plugin that generates the service worker. After a production build, it writes `sw.js` into the config's outDir, once the client bundle is written. During development, the dev server answers `/sw.js` with a worker generated with `caching: false`, so every request reaches the dev server and updates show up without stale caches. Paths are resolved from Vite's root unless `cwd` is set. When generating fails, the build fails with writeServiceWorker's error, and the dev server answers the worker's request with it.
+
+```ts
+serviceWorkerPlugin(
+  options: { config: string | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string } } & IBuildServiceWorkerOptions,
+): Plugin
+```
+
+**Parameters**
+
+- `options` `{ config: string | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string } } & IBuildServiceWorkerOptions`: The config, as a file path or an object, plus the build options. The dev server uses the environment option, or `development` when it isn't set.
+
+**Returns** `Plugin`: The Vite plugin.
+
+**Example**
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { serviceWorkerPlugin } from 'jg-sw/build';
+
+export default defineConfig({
+  plugins: [serviceWorkerPlugin({ config: 'jg-sw.config.json', environment: 'production' })],
+});
+```
+
+#### <a id="api-build-writeServiceWorker"></a>`writeServiceWorker`
+
+*Function*
+
+Generates the service worker and writes it to `sw.js` in the config's outDir, after the app's build has written its files there.
+
+```ts
+writeServiceWorker(
+  config: { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string },
+  options?: IBuildServiceWorkerOptions,
+): Promise<string>
+```
+
+**Parameters**
+
+- `config` `{ outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "base" } | { outDir: string; cacheNamePrefix: string; includeToPrecache: string[]; excludeFilesFromPrecache: string[]; excludeMIMETypesFromCache: string[]; template: "firebase-fcm"; firebaseConfigProcessEnvKey: string; firebaseSdkVersion: string }`: The service worker config, as read by readServiceWorkerConfig or written inline.
+- `options?` `IBuildServiceWorkerOptions`: The environment the firebase-fcm template reads its Firebase config from, whether the worker caches (false for development), and the directory paths are resolved from. Defaults to `{}`.
+
+**Returns** `Promise<string>`: A promise that resolves to the written file's path.
+
+**Throws**
+
+- `FAILED_TO_READ_BASE_CONFIG`: The service worker config is invalid.
+- `INVALID_TEMPLATE_NAME`: The template must be 'base' or 'firebase-fcm'.
+- `INVALID_FIREBASE_SDK_VERSION`: The Firebase SDK version must be a version such as 12.4.0.
+- `INVALID_ENVIRONMENT`: The environment isn't supported, or the firebase-fcm template needs one.
+- `NOT_A_PATH_ELEMENT`: An asset to precache is outside outDir, or isn't a file or a directory.
+- `FAILED_TO_BUILD_CONFIG`: Unable to load the environment file.
+- `INVALID_FIREBASE_CONFIG`: The environment variable that holds the Firebase config is missing or
+- empty.
+- `FAILED_TO_READ_FIREBASE_CONFIG`: Unable to read the Firebase config from the environment
+- variable.
+
+**Example**
+
+```ts
+import { readServiceWorkerConfig, writeServiceWorker } from 'jg-sw/build';
+
+const config = await readServiceWorkerConfig('jg-sw.config.json');
+await writeServiceWorker(config, { environment: 'production' }); // '/app/dist/sw.js'
+```
+
+### <a id="api-build-constants"></a>Constants in `jg-sw/build`
+
+#### <a id="api-build-ERRORS"></a>`ERRORS`
+
+*Constant*
+
+the codes for every error thrown by the build side
+
+```ts
+const ERRORS: { INVALID_TEMPLATE_NAME: "INVALID_TEMPLATE_NAME"; NOT_A_PATH_ELEMENT: "NOT_A_PATH_ELEMENT"; FAILED_TO_READ_BASE_CONFIG: "FAILED_TO_READ_BASE_CONFIG"; INVALID_FIREBASE_CONFIG: "INVALID_FIREBASE_CONFIG"; INVALID_ENVIRONMENT: "INVALID_ENVIRONMENT"; FAILED_TO_BUILD_CONFIG: "FAILED_TO_BUILD_CONFIG"; FAILED_TO_READ_FIREBASE_CONFIG: "FAILED_TO_READ_FIREBASE_CONFIG"; INVALID_FIREBASE_SDK_VERSION: "INVALID_FIREBASE_SDK_VERSION" }
+```
+
+#### <a id="api-build-ServiceWorkerConfigSchema"></a>`ServiceWorkerConfigSchema`
+
+*Constant*
+
+The schema of a service worker config: the `jg-sw.config.json` file the CLI reads, or the object passed to `buildServiceWorker`. `template` selects the worker: `base` caches the app, and `firebase-fcm` also shows Firebase Cloud Messaging notifications.
+
+```ts
+const ServiceWorkerConfigSchema: ZodDiscriminatedUnion<[ZodObject<{ outDir: ZodString; cacheNamePrefix: ZodString; includeToPrecache: ZodArray<ZodString>; excludeFilesFromPrecache: ZodArray<ZodString>; excludeMIMETypesFromCache: ZodArray<ZodString>; template: ZodLiteral<"base"> }, $strict>, ZodObject<{ outDir: ZodString; cacheNamePrefix: ZodString; includeToPrecache: ZodArray<ZodString>; excludeFilesFromPrecache: ZodArray<ZodString>; excludeMIMETypesFromCache: ZodArray<ZodString>; template: ZodLiteral<"firebase-fcm">; firebaseConfigProcessEnvKey: ZodString; firebaseSdkVersion: ZodString }, $strict>], "template">
+```
+
+**Example**
+
+```ts
+import { ServiceWorkerConfigSchema } from 'jg-sw/build';
+
+const config = ServiceWorkerConfigSchema.parse({
+  outDir: 'dist',
+  cacheNamePrefix: 'my-app',
+  template: 'base',
+  includeToPrecache: ['/', '/index.html', '/assets'],
+  excludeFilesFromPrecache: [],
+  excludeMIMETypesFromCache: ['application/json'],
+});
+```
+
+### <a id="api-build-types"></a>Types in `jg-sw/build`
+
+#### <a id="api-build-IBuildServiceWorkerOptions"></a>`IBuildServiceWorkerOptions`
+
+*Type*
+
+the options buildServiceWorker and writeServiceWorker accept
+
+```ts
+type IBuildServiceWorkerOptions = {
+    environment?: 'development' | 'staging' | 'production';
+    caching?: boolean;
+    cwd?: string;
+};
+```
+
+**Members**
+
+- `environment: "development" | "staging" | "production"` (property): the environment whose file the firebase-fcm template reads its Firebase config from: .env, .env.staging, or .env.production. The firebase-fcm template requires it
+- `caching: boolean` (property): false leaves out precaching, cache cleanup, and the fetch handler, for development. Defaults to true
+- `cwd: string` (property): the directory outDir and the environment files are resolved from. Defaults to process.cwd()
+
+#### <a id="api-build-IServiceWorkerConfig"></a>`IServiceWorkerConfig`
+
+*Type*
+
+a service worker config, validated by ServiceWorkerConfigSchema
+
+```ts
+type IServiceWorkerConfig = z.infer<typeof ServiceWorkerConfigSchema>;
+```

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.1.0
+
+A fresh start: breaking changes in a minor version, once, because nothing depended on 1.0.x.
+
+### Added
+
+- `ERRORS.SW_REGISTRATION_FAILED`, the code of a registration the browser rejects, with the browser's error as `cause`.
+- `API.md`, the full API reference, generated from the TSDoc of the version it ships with, so it can be read from `node_modules` without a browser.
+
+### Changed
+
+- `registrationError` in the snapshot is an `Exception` with one of the `ERRORS` codes, instead of an encoded message.
+- Errors are `Exception`s from `jg-exception` 1.1.0: the code, the data, and the cause each have their own field, nothing is encoded into the message, and `toJSON()` and `toString()` follow `jg-exception`.
+- Error messages say what failed at that step and keep the error underneath as `cause`, instead of repeating its message, so `extractMessage` prints each layer of the chain once.
+
 ## 1.0.1
 
 ### Changed
@@ -8,35 +23,13 @@
 
 ## 1.0.0
 
-The first release of `jg-sw`, which replaces `sw-service` 1.2.0 and `sw-builder` 1.2.1.
+The first release.
 
 ### Added
 
-- `registerServiceWorker`, `getServiceWorkerSnapshot`, `subscribeToServiceWorker`, `updateApp`, `canInstallApp`, and `installApp`, which replace the `SWService` object, with `ERRORS` and the `REGISTRATION_DURATION_SECONDS`, `UPDATE_INSTALL_TIMEOUT_SECONDS`, `DEFAULT_SERVICE_WORKER_PATH`, `DEFAULT_SERVICE_WORKER_SCOPE`, and `SKIP_WAITING_MESSAGE_TYPE` constants.
+- `registerServiceWorker`, `getServiceWorkerSnapshot`, `subscribeToServiceWorker`, `updateApp`, `canInstallApp`, and `installApp`, with `ERRORS` and the `REGISTRATION_DURATION_SECONDS`, `UPDATE_INSTALL_TIMEOUT_SECONDS`, `DEFAULT_SERVICE_WORKER_PATH`, `DEFAULT_SERVICE_WORKER_SCOPE`, and `SKIP_WAITING_MESSAGE_TYPE` constants.
 - A snapshot whose identity changes only with the state, for `useSyncExternalStore`, with `hasWaitingWorker` and the installation state.
 - `jg-sw/build`, with `buildServiceWorker`, `writeServiceWorker`, `readServiceWorkerConfig`, `ServiceWorkerConfigSchema`, and `ERRORS`, the codes of every error it throws.
 - `serviceWorkerPlugin`, a Vite plugin that writes the worker after a build and serves it without caching in development.
 - The `jg-sw` CLI, with `--config`, `--environment`, `--no-caching`, and `--help`.
-- The worker activates when the page posts the skip-waiting message.
-- `caching: false` and `--no-caching`, which generate a worker without precaching, cache cleanup, or a fetch handler.
-- The `INVALID_FIREBASE_SDK_VERSION` code.
-
-### Changed
-
-- `updateApp()` activates the waiting worker and reloads once it controls the page. Without one, it waits up to 30 seconds for a new worker to install, and reloads as it is when none installs.
-- `registerServiceWorker()` resolves once the registration settles, never rejects, and returns the first call's promise on later calls.
-- `installApp()` resolves to the prompt's outcome.
-- The install prompt is tracked from the first `registerServiceWorker()` call, before the registration settles.
-- Logs appear only with `debugMode`, and nothing touches `window` or `navigator` when the module loads.
-- The worker never caches responses marked `Cache-Control: no-store` or `private`.
-- The config file is named `jg-sw.config.json`, and the Firebase background hook `self.jgSwFcmBackgroundMessageHandler`.
-- `firebaseSdkVersion` must be a version such as `12.4.0`. An invalid template fails with `INVALID_TEMPLATE_NAME`, and an unsupported environment with `INVALID_ENVIRONMENT`, whatever the template.
-- Environment files load with Node.js's `process.loadEnvFile`.
-- Precached paths are URL paths from `outDir`, with `#`, `?`, and `%` percent-encoded and each directory's files sorted. A path outside `outDir` fails with `NOT_A_PATH_ELEMENT`.
-- Values written into the worker are serialized as JSON.
-- Errors are `Exception`s from `jg-exception`.
-
-### Removed
-
-- The `SWService` object and its `ISWService`, `IAppInstallerService`, and `ISWRegistrationOptions` types.
-- Running the CLI on import, and the `dotenv` and `argv-utils` dependencies.
+- A generated worker that activates when the page posts the skip-waiting message, never caches responses marked `Cache-Control: no-store` or `private`, and can be generated without caching for development.