@oxy.so/core 7.9.2 → 7.10.0

package/dist/cjs/api/storeInstaller.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * The store's installer: how a store installs, opens and updates an application on a machine
+ * that installs applications, beside `oxy.store`, which reads the catalogue.
+ *
+ * `oxy.store` says what the store lists; an installer says what the machine can do with a
+ * listing. A runtime that installs applications registers one (OxyOS's Bloom host registers one
+ * backed by the system's install service before the application's code runs, OxyOS ADR 0030
+ * decision 9; ADR 0053 here). Where none is registered — the web, iOS, Android — there is
+ * nothing to install, and a store shows what it shows without one. An application never asks
+ * which platform it runs on: it asks whether there is an installer.
+ *
+ * The installer is the store's hands, never its judge. It is given a listing's slug and nothing
+ * else: the machine resolves slug → package → release from the store's signed metadata, verifies
+ * it, and asks the person in a sheet of its own that no application can draw or press. The store
+ * learns the outcome and nothing of the sheet. Its errors say whether the machine already told the
+ * person (`told`), so a store never repeats what the system said.
+ *
+ * React-free and dependency-free, as everything in `@oxy.so/core`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StoreInstallerError = void 0;
+exports.setStoreInstaller = setStoreInstaller;
+exports.getStoreInstaller = getStoreInstaller;
+/** A failure of an installer's request. */
+class StoreInstallerError extends Error {
+    constructor(reason, options = {}) {
+        super(options.message ?? reason);
+        this.name = 'StoreInstallerError';
+        this.reason = reason;
+        this.told = options.told ?? false;
+    }
+}
+exports.StoreInstallerError = StoreInstallerError;
+let installer = null;
+/**
+ * Registers the machine's installer, or removes it with null. A runtime calls it once, before
+ * the application's code runs; nothing else should.
+ */
+function setStoreInstaller(next) {
+    installer = next;
+}
+/** The machine's installer, or null where nothing installs applications. */
+function getStoreInstaller() {
+    return installer;
+}

package/dist/cjs/index.js

@@ -21,10 +21,10 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.OxyAppDataIdentifierError = exports.AccountNotOnDeviceError = exports.REPUTATION_CACHE_PREFIX = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.buildUserDid = exports.DirectUploadInterruptedError = exports.MAX_UPLOAD_BYTES = exports.assetUrlCacheTTL = exports.ASSET_MULTIPART_UPLOAD_MAX_BYTES = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyApiError = exports.OXY_CLOUD_URL = exports.OXY_API_URL = exports.OxyServices = void 0;
-exports.accountCategoryLabel = exports.getLocalesVersion = exports.subscribeLocales = exports.isLocaleLoaded = exports.loadLocale = exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.coerceToSupportedLocale = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = void 0;
-exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.accountNameInvalidKey = exports.accountNameInvalidMessage = exports.accountNameMaxLength = exports.isValidAccountName = exports.isValidDisplayName = exports.isValidPassword = exports.isValidEmail = exports.ACCOUNT_TITLE_INVALID_MESSAGE = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.parseHttpErrorBody = exports.isHttpRequestError = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.trustTierLabel = exports.reputationCategoryLabel = exports.accountRoleLabel = void 0;
-exports.packageInfo = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.CENTRAL_IDP_APEX = exports.AUTH_WEB_ORIGIN = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = void 0;
+exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.OxyAppDataIdentifierError = exports.AccountNotOnDeviceError = exports.REPUTATION_CACHE_PREFIX = exports.StoreInstallerError = exports.setStoreInstaller = exports.getStoreInstaller = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.buildUserDid = exports.DirectUploadInterruptedError = exports.MAX_UPLOAD_BYTES = exports.assetUrlCacheTTL = exports.ASSET_MULTIPART_UPLOAD_MAX_BYTES = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyApiError = exports.OXY_CLOUD_URL = exports.OXY_API_URL = exports.OxyServices = void 0;
+exports.isLocaleLoaded = exports.loadLocale = exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.coerceToSupportedLocale = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = void 0;
+exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.accountNameInvalidKey = exports.accountNameInvalidMessage = exports.accountNameMaxLength = exports.isValidAccountName = exports.isValidDisplayName = exports.isValidPassword = exports.isValidEmail = exports.ACCOUNT_TITLE_INVALID_MESSAGE = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.parseHttpErrorBody = exports.isHttpRequestError = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.trustTierLabel = exports.reputationCategoryLabel = exports.accountRoleLabel = exports.accountCategoryLabel = exports.getLocalesVersion = exports.subscribeLocales = void 0;
+exports.packageInfo = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.CENTRAL_IDP_APEX = exports.AUTH_WEB_ORIGIN = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = void 0;
 // The crypto shim MUST stay the first import. The root itself ships no crypto
 // library (`__tests__/rootEntryGraph.test.ts`), but `@oxy.so/protocol`'s root
 // entry (reached by the OAuth/PKCE and device helpers) does, and Metro does not
@@ -58,6 +58,12 @@ Object.defineProperty(exports, "MAX_ACCOUNT_CATEGORIES", { enumerable: true, get
 Object.defineProperty(exports, "SELECTABLE_ACCOUNT_CATEGORY_IDS", { enumerable: true, get: function () { return accounts_1.SELECTABLE_ACCOUNT_CATEGORY_IDS; } });
 Object.defineProperty(exports, "isSelectableAccountCategoryId", { enumerable: true, get: function () { return accounts_1.isSelectableAccountCategoryId; } });
 Object.defineProperty(exports, "kindAcceptsAccountCategories", { enumerable: true, get: function () { return accounts_1.kindAcceptsAccountCategories; } });
+// The store's installer (ADR 0053): what a runtime that installs applications registers beside
+// `oxy.store`, and what a store asks it.
+var storeInstaller_1 = require("./api/storeInstaller");
+Object.defineProperty(exports, "getStoreInstaller", { enumerable: true, get: function () { return storeInstaller_1.getStoreInstaller; } });
+Object.defineProperty(exports, "setStoreInstaller", { enumerable: true, get: function () { return storeInstaller_1.setStoreInstaller; } });
+Object.defineProperty(exports, "StoreInstallerError", { enumerable: true, get: function () { return storeInstaller_1.StoreInstallerError; } });
 var reputation_1 = require("./api/reputation");
 Object.defineProperty(exports, "REPUTATION_CACHE_PREFIX", { enumerable: true, get: function () { return reputation_1.REPUTATION_CACHE_PREFIX; } });
 var devices_1 = require("./api/devices");

package/dist/esm/api/storeInstaller.js

@@ -0,0 +1,40 @@
+/**
+ * The store's installer: how a store installs, opens and updates an application on a machine
+ * that installs applications, beside `oxy.store`, which reads the catalogue.
+ *
+ * `oxy.store` says what the store lists; an installer says what the machine can do with a
+ * listing. A runtime that installs applications registers one (OxyOS's Bloom host registers one
+ * backed by the system's install service before the application's code runs, OxyOS ADR 0030
+ * decision 9; ADR 0053 here). Where none is registered — the web, iOS, Android — there is
+ * nothing to install, and a store shows what it shows without one. An application never asks
+ * which platform it runs on: it asks whether there is an installer.
+ *
+ * The installer is the store's hands, never its judge. It is given a listing's slug and nothing
+ * else: the machine resolves slug → package → release from the store's signed metadata, verifies
+ * it, and asks the person in a sheet of its own that no application can draw or press. The store
+ * learns the outcome and nothing of the sheet. Its errors say whether the machine already told the
+ * person (`told`), so a store never repeats what the system said.
+ *
+ * React-free and dependency-free, as everything in `@oxy.so/core`.
+ */
+/** A failure of an installer's request. */
+export class StoreInstallerError extends Error {
+    constructor(reason, options = {}) {
+        super(options.message ?? reason);
+        this.name = 'StoreInstallerError';
+        this.reason = reason;
+        this.told = options.told ?? false;
+    }
+}
+let installer = null;
+/**
+ * Registers the machine's installer, or removes it with null. A runtime calls it once, before
+ * the application's code runs; nothing else should.
+ */
+export function setStoreInstaller(next) {
+    installer = next;
+}
+/** The machine's installer, or null where nothing installs applications. */
+export function getStoreInstaller() {
+    return installer;
+}

package/dist/esm/index.js

@@ -34,6 +34,9 @@ export { ASSET_MULTIPART_UPLOAD_MAX_BYTES, assetUrlCacheTTL, MAX_UPLOAD_BYTES }
 export { DirectUploadInterruptedError } from './api/directUpload.js';
 export { buildUserDid } from './api/identity.js';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './api/accounts.js';
+// The store's installer (ADR 0053): what a runtime that installs applications registers beside
+// `oxy.store`, and what a store asks it.
+export { getStoreInstaller, setStoreInstaller, StoreInstallerError, } from './api/storeInstaller.js';
 export { REPUTATION_CACHE_PREFIX } from './api/reputation.js';
 export { AccountNotOnDeviceError } from './api/devices.js';
 export { OxyAppDataIdentifierError } from './api/appData.js';

package/dist/types/api/storeInstaller.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The store's installer: how a store installs, opens and updates an application on a machine
+ * that installs applications, beside `oxy.store`, which reads the catalogue.
+ *
+ * `oxy.store` says what the store lists; an installer says what the machine can do with a
+ * listing. A runtime that installs applications registers one (OxyOS's Bloom host registers one
+ * backed by the system's install service before the application's code runs, OxyOS ADR 0030
+ * decision 9; ADR 0053 here). Where none is registered — the web, iOS, Android — there is
+ * nothing to install, and a store shows what it shows without one. An application never asks
+ * which platform it runs on: it asks whether there is an installer.
+ *
+ * The installer is the store's hands, never its judge. It is given a listing's slug and nothing
+ * else: the machine resolves slug → package → release from the store's signed metadata, verifies
+ * it, and asks the person in a sheet of its own that no application can draw or press. The store
+ * learns the outcome and nothing of the sheet. Its errors say whether the machine already told the
+ * person (`told`), so a store never repeats what the system said.
+ *
+ * React-free and dependency-free, as everything in `@oxy.so/core`.
+ */
+/** Where a listing stands on this machine, for the action a store's page shows. */
+export type StoreInstallState = 
+/** The store has a release this machine can run, and it is not installed: *Get*. */
+{
+    state: 'notInstalled';
+}
+/** Being installed or updated: a progress ring. `fraction` is null while it cannot be told. */
+ | {
+    state: 'installing';
+    fraction: number | null;
+}
+/** Installed and current: *Open*. */
+ | {
+    state: 'installed';
+    version: string;
+}
+/**
+ * Installed, with a newer release: *Update*. `needsConsent` when the newer release asks for
+ * more than the installed one, which the machine asks the person for in its own sheet.
+ */
+ | {
+    state: 'updateAvailable';
+    version: string;
+    newVersion: string;
+    needsConsent: boolean;
+}
+/** The store has no release this machine can run: *Not available for this computer*. */
+ | {
+    state: 'unavailable';
+};
+/** Why the machine could not do what the store asked. */
+export type StoreInstallerFailure = 
+/** The machine's install service is not running. */
+'serviceUnavailable'
+/** The store has no release of it this machine can run. */
+ | 'notAvailable'
+/** It is not installed (opening or updating it). */
+ | 'notInstalled'
+/** The installer refused the request (it lacks the right to install, or it was not a person's press). */
+ | 'refused'
+/** The install or update itself failed (a download, a verification, a compile). */
+ | 'failed';
+/** A failure of an installer's request. */
+export declare class StoreInstallerError extends Error {
+    readonly reason: StoreInstallerFailure;
+    /**
+     * Whether the machine already told the person, in its own sheet. A store says nothing more
+     * when it did: the system's word is the one the person reads.
+     */
+    readonly told: boolean;
+    constructor(reason: StoreInstallerFailure, options?: {
+        told?: boolean;
+        message?: string;
+    });
+}
+/** An update the machine has for an installed application. */
+export interface StoreUpdate {
+    /** The installer's own id for the application; what `apply` takes. Never a slug. */
+    id: string;
+    /** Its name in the person's language, from the store's signed metadata. */
+    name: string;
+    /** The version installed, and the one the update brings. */
+    version: string;
+    newVersion: string;
+    /** Bytes the machine would fetch: only what it does not have already. */
+    downloadSize: number;
+    /** What is new, in the person's language, or null when the release says nothing. */
+    releaseNotes: string | null;
+    /** The update asks for more than the installed version: the machine asks the person first. */
+    needsConsent: boolean;
+    /** Applied, waiting for the running copy to quit: it runs at its next launch. */
+    atNextLaunch: boolean;
+}
+/** The machine's updates for this account: one state, which every page that shows updates reads. */
+export interface StoreUpdates {
+    updates: StoreUpdate[];
+    /** A check of the store is running. */
+    checking: boolean;
+    /** When the store was last read (ISO 8601), or null. */
+    lastChecked: string | null;
+    /** The last check failed. */
+    checkFailed: boolean;
+}
+/** The machine's updates, as one state that changes by itself. */
+export interface StoreUpdatesSource {
+    /** The state last told, or null before the machine has said. */
+    current(): StoreUpdates | null;
+    /**
+     * The state as it is now, asked of the machine without reading the store. Rejects with a
+     * `StoreInstallerError` when the machine cannot say (its install service is not running).
+     */
+    read(): Promise<StoreUpdates>;
+    /** Reads the store now. A check asked while one runs joins it. */
+    check(): Promise<StoreUpdates>;
+    /** Applies these updates; one that needs consent is asked in the machine's sheet first. */
+    apply(ids: readonly string[]): Promise<void>;
+    /** Applies every update, asking for consent in turn after the rest. */
+    applyAll(): Promise<void>;
+    /** Told each change; returns the unsubscribe. */
+    subscribe(listener: (updates: StoreUpdates) => void): () => void;
+}
+/**
+ * What a runtime that installs applications gives a store. Every action that changes anything is
+ * asked from a person's press: the machine refuses what the person did not ask for.
+ */
+export interface StoreInstaller {
+    /**
+     * Where each listing stands. Rejects with a `StoreInstallerError` when the machine cannot say
+     * (its install service is not running): a store then shows its usual action and lets the
+     * machine say why when it is pressed.
+     */
+    status(slugs: readonly string[]): Promise<Record<string, StoreInstallState>>;
+    /**
+     * Installs a listing's application: the machine's sheet, then the install. Resolves when the
+     * person declined in the sheet or the install is done; the progress in between is told to
+     * `subscribe`'s listeners as `installing`.
+     */
+    install(slug: string): Promise<'installed' | 'declined'>;
+    /** Updates it, asking in the machine's sheet when the update needs the person's consent. */
+    update(slug: string): Promise<'updated' | 'declined'>;
+    /** Removes it and its data, after the machine's sheet. */
+    uninstall(slug: string): Promise<'removed' | 'declined'>;
+    /** Opens the installed application. */
+    open(slug: string): Promise<void>;
+    /** Told each listing whose state changed; returns the unsubscribe. */
+    subscribe(listener: (slug: string, state: StoreInstallState) => void): () => void;
+    /** The account's updates (a store's *Updates* page). */
+    readonly updates: StoreUpdatesSource;
+}
+/**
+ * Registers the machine's installer, or removes it with null. A runtime calls it once, before
+ * the application's code runs; nothing else should.
+ */
+export declare function setStoreInstaller(next: StoreInstaller | null): void;
+/** The machine's installer, or null where nothing installs applications. */
+export declare function getStoreInstaller(): StoreInstaller | null;

package/dist/types/index.d.ts

@@ -45,6 +45,8 @@ export type { AppsApi, AppAssertionsApi, Application, ApplicationType, Applicati
 export type { LinkedAccountsApi } from './api/linkedAccounts';
 export type { AgencyApi, AccountCapabilityPolicy, AvailableCapabilityCatalog, CapabilityExecutionAuthorization, CreateDelegationGrantInput, DelegationCatalogBinding, DelegationGrantView, PutAccountCapabilityPolicyInput, UpdateDelegationGrantInput, } from './api/agency';
 export type { StoreApi, StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './api/store';
+export { getStoreInstaller, setStoreInstaller, StoreInstallerError, } from './api/storeInstaller';
+export type { StoreInstallState, StoreInstaller, StoreInstallerFailure, StoreUpdate, StoreUpdates, StoreUpdatesSource, } from './api/storeInstaller';
 export type { BillingApi, SubscriptionPlan, SubscriptionStatus, SubscriptionFeatures, Subscription, Payment, WalletTransactionType, WalletTransactionStatus, WalletTransaction, WalletPagination, WalletTransactionsPage, } from './api/billing';
 export { REPUTATION_CACHE_PREFIX } from './api/reputation';
 export type { ReputationApi, ReputationPage } from './api/reputation';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.9.2",
+  "version": "7.10.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/api/storeInstaller.ts

@@ -0,0 +1,158 @@
+/**
+ * The store's installer: how a store installs, opens and updates an application on a machine
+ * that installs applications, beside `oxy.store`, which reads the catalogue.
+ *
+ * `oxy.store` says what the store lists; an installer says what the machine can do with a
+ * listing. A runtime that installs applications registers one (OxyOS's Bloom host registers one
+ * backed by the system's install service before the application's code runs, OxyOS ADR 0030
+ * decision 9; ADR 0053 here). Where none is registered — the web, iOS, Android — there is
+ * nothing to install, and a store shows what it shows without one. An application never asks
+ * which platform it runs on: it asks whether there is an installer.
+ *
+ * The installer is the store's hands, never its judge. It is given a listing's slug and nothing
+ * else: the machine resolves slug → package → release from the store's signed metadata, verifies
+ * it, and asks the person in a sheet of its own that no application can draw or press. The store
+ * learns the outcome and nothing of the sheet. Its errors say whether the machine already told the
+ * person (`told`), so a store never repeats what the system said.
+ *
+ * React-free and dependency-free, as everything in `@oxy.so/core`.
+ */
+
+/** Where a listing stands on this machine, for the action a store's page shows. */
+export type StoreInstallState =
+  /** The store has a release this machine can run, and it is not installed: *Get*. */
+  | { state: 'notInstalled' }
+  /** Being installed or updated: a progress ring. `fraction` is null while it cannot be told. */
+  | { state: 'installing'; fraction: number | null }
+  /** Installed and current: *Open*. */
+  | { state: 'installed'; version: string }
+  /**
+   * Installed, with a newer release: *Update*. `needsConsent` when the newer release asks for
+   * more than the installed one, which the machine asks the person for in its own sheet.
+   */
+  | { state: 'updateAvailable'; version: string; newVersion: string; needsConsent: boolean }
+  /** The store has no release this machine can run: *Not available for this computer*. */
+  | { state: 'unavailable' };
+
+/** Why the machine could not do what the store asked. */
+export type StoreInstallerFailure =
+  /** The machine's install service is not running. */
+  | 'serviceUnavailable'
+  /** The store has no release of it this machine can run. */
+  | 'notAvailable'
+  /** It is not installed (opening or updating it). */
+  | 'notInstalled'
+  /** The installer refused the request (it lacks the right to install, or it was not a person's press). */
+  | 'refused'
+  /** The install or update itself failed (a download, a verification, a compile). */
+  | 'failed';
+
+/** A failure of an installer's request. */
+export class StoreInstallerError extends Error {
+  readonly reason: StoreInstallerFailure;
+  /**
+   * Whether the machine already told the person, in its own sheet. A store says nothing more
+   * when it did: the system's word is the one the person reads.
+   */
+  readonly told: boolean;
+
+  constructor(reason: StoreInstallerFailure, options: { told?: boolean; message?: string } = {}) {
+    super(options.message ?? reason);
+    this.name = 'StoreInstallerError';
+    this.reason = reason;
+    this.told = options.told ?? false;
+  }
+}
+
+/** An update the machine has for an installed application. */
+export interface StoreUpdate {
+  /** The installer's own id for the application; what `apply` takes. Never a slug. */
+  id: string;
+  /** Its name in the person's language, from the store's signed metadata. */
+  name: string;
+  /** The version installed, and the one the update brings. */
+  version: string;
+  newVersion: string;
+  /** Bytes the machine would fetch: only what it does not have already. */
+  downloadSize: number;
+  /** What is new, in the person's language, or null when the release says nothing. */
+  releaseNotes: string | null;
+  /** The update asks for more than the installed version: the machine asks the person first. */
+  needsConsent: boolean;
+  /** Applied, waiting for the running copy to quit: it runs at its next launch. */
+  atNextLaunch: boolean;
+}
+
+/** The machine's updates for this account: one state, which every page that shows updates reads. */
+export interface StoreUpdates {
+  updates: StoreUpdate[];
+  /** A check of the store is running. */
+  checking: boolean;
+  /** When the store was last read (ISO 8601), or null. */
+  lastChecked: string | null;
+  /** The last check failed. */
+  checkFailed: boolean;
+}
+
+/** The machine's updates, as one state that changes by itself. */
+export interface StoreUpdatesSource {
+  /** The state last told, or null before the machine has said. */
+  current(): StoreUpdates | null;
+  /**
+   * The state as it is now, asked of the machine without reading the store. Rejects with a
+   * `StoreInstallerError` when the machine cannot say (its install service is not running).
+   */
+  read(): Promise<StoreUpdates>;
+  /** Reads the store now. A check asked while one runs joins it. */
+  check(): Promise<StoreUpdates>;
+  /** Applies these updates; one that needs consent is asked in the machine's sheet first. */
+  apply(ids: readonly string[]): Promise<void>;
+  /** Applies every update, asking for consent in turn after the rest. */
+  applyAll(): Promise<void>;
+  /** Told each change; returns the unsubscribe. */
+  subscribe(listener: (updates: StoreUpdates) => void): () => void;
+}
+
+/**
+ * What a runtime that installs applications gives a store. Every action that changes anything is
+ * asked from a person's press: the machine refuses what the person did not ask for.
+ */
+export interface StoreInstaller {
+  /**
+   * Where each listing stands. Rejects with a `StoreInstallerError` when the machine cannot say
+   * (its install service is not running): a store then shows its usual action and lets the
+   * machine say why when it is pressed.
+   */
+  status(slugs: readonly string[]): Promise<Record<string, StoreInstallState>>;
+  /**
+   * Installs a listing's application: the machine's sheet, then the install. Resolves when the
+   * person declined in the sheet or the install is done; the progress in between is told to
+   * `subscribe`'s listeners as `installing`.
+   */
+  install(slug: string): Promise<'installed' | 'declined'>;
+  /** Updates it, asking in the machine's sheet when the update needs the person's consent. */
+  update(slug: string): Promise<'updated' | 'declined'>;
+  /** Removes it and its data, after the machine's sheet. */
+  uninstall(slug: string): Promise<'removed' | 'declined'>;
+  /** Opens the installed application. */
+  open(slug: string): Promise<void>;
+  /** Told each listing whose state changed; returns the unsubscribe. */
+  subscribe(listener: (slug: string, state: StoreInstallState) => void): () => void;
+  /** The account's updates (a store's *Updates* page). */
+  readonly updates: StoreUpdatesSource;
+}
+
+let installer: StoreInstaller | null = null;
+
+/**
+ * Registers the machine's installer, or removes it with null. A runtime calls it once, before
+ * the application's code runs; nothing else should.
+ */
+export function setStoreInstaller(next: StoreInstaller | null): void {
+  installer = next;
+}
+
+/** The machine's installer, or null where nothing installs applications. */
+export function getStoreInstaller(): StoreInstaller | null {
+  return installer;
+}

package/src/index.ts

@@ -206,6 +206,21 @@ export type {
   StorePageOptions,
   StoreReviewsOptions,
 } from './api/store';
+// The store's installer (ADR 0053): what a runtime that installs applications registers beside
+// `oxy.store`, and what a store asks it.
+export {
+  getStoreInstaller,
+  setStoreInstaller,
+  StoreInstallerError,
+} from './api/storeInstaller';
+export type {
+  StoreInstallState,
+  StoreInstaller,
+  StoreInstallerFailure,
+  StoreUpdate,
+  StoreUpdates,
+  StoreUpdatesSource,
+} from './api/storeInstaller';
 export type {
   BillingApi,
   SubscriptionPlan,