@oxy.so/core 1.0.0

package/dist/cjs/mixins/OxyServices.inference.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * The inference API, reached with whatever bearer this session already holds
+ * (issue #972, workstream 15).
+ *
+ * ```typescript
+ * const models = await oxyServices.inference().listModels();
+ * ```
+ *
+ * One method, and it is a FACTORY rather than a set of inference methods on
+ * `OxyServices`. The calls themselves live once, in
+ * {@link OxyInferenceClient} — which an external developer holding only an
+ * `oxy_sk_…` machine key constructs directly, with no Oxy session anywhere in
+ * the picture. Declaring the same calls a second time here would give the
+ * ecosystem two spellings of one request, and only one of them would stay
+ * correct.
+ *
+ * This is the reasoning `createLinkedClient` is already built on: the plumbing
+ * that binds an Oxy bearer to a client belongs in core, once, rather than in
+ * each app.
+ *
+ * The credential is a FUNCTION, not the current token: a session bearer rotates
+ * on refresh and on account switch, and a client that captured one at
+ * construction would start answering 401 an hour into the process's life.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesInferenceMixin = OxyServicesInferenceMixin;
+const OxyInferenceClient_1 = require("../inference/OxyInferenceClient");
+function OxyServicesInferenceMixin(Base) {
+    return class extends Base {
+        constructor() {
+            super(...arguments);
+            /** @internal Memoized so repeated calls return one object identity. */
+            this._inferenceClient = null;
+        }
+        /**
+         * The inference client for this session.
+         *
+         * Bound to this instance's base URL and to `getAccessToken()`, so it
+         * follows every refresh, sign-in and account switch without being
+         * rebuilt.
+         *
+         * A service-authenticated process wants a different credential and
+         * builds {@link OxyInferenceClient} directly:
+         * `new OxyInferenceClient({ credential: () => oxy.getServiceToken() })`.
+         * The mint is asynchronous and cached, which is exactly what a
+         * credential function is for.
+         */
+        inference() {
+            if (this._inferenceClient === null) {
+                this._inferenceClient = new OxyInferenceClient_1.OxyInferenceClient({
+                    baseURL: this.getBaseURL(),
+                    credential: () => this.getAccessToken(),
+                });
+            }
+            return this._inferenceClient;
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.language.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesLanguageMixin = OxyServicesLanguageMixin;
+/**
+ * Language Methods Mixin
+ */
+const languageUtils_1 = require("../utils/languageUtils");
+const protocol_1 = require("@oxy.so/protocol");
+const logger_1 = require("../logger");
+function OxyServicesLanguageMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Get appropriate storage for the platform (similar to DeviceManager)
+         */
+        async getStorage() {
+            const isReactNative = typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+            if (isReactNative) {
+                try {
+                    // `loadAsyncStorage` is per-platform: the RN variant statically imports
+                    // @react-native-async-storage/async-storage, the default variant throws
+                    // (never called outside RN because of the `isReactNative` gate above).
+                    const asyncStorageModule = await (0, protocol_1.loadAsyncStorage)();
+                    const storage = asyncStorageModule.default;
+                    return {
+                        getItem: storage.getItem.bind(storage),
+                        setItem: storage.setItem.bind(storage),
+                        removeItem: storage.removeItem.bind(storage),
+                    };
+                }
+                catch (error) {
+                    logger_1.logger.error('AsyncStorage not available in React Native', error, { component: 'OxyServices.language' });
+                    throw new Error('AsyncStorage is required in React Native environment');
+                }
+            }
+            else {
+                // Use localStorage for web
+                return {
+                    getItem: async (key) => {
+                        if (typeof window !== 'undefined' && window.localStorage) {
+                            return localStorage.getItem(key);
+                        }
+                        return null;
+                    },
+                    setItem: async (key, value) => {
+                        if (typeof window !== 'undefined' && window.localStorage) {
+                            localStorage.setItem(key, value);
+                        }
+                    },
+                    removeItem: async (key) => {
+                        if (typeof window !== 'undefined' && window.localStorage) {
+                            localStorage.removeItem(key);
+                        }
+                    }
+                };
+            }
+        }
+        /**
+         * Get the current locale from the user profile or local storage.
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns The current BCP-47 locale (e.g., 'en-US') or null if not set
+         */
+        async getCurrentLanguage(storageKeyPrefix = 'oxy_session') {
+            try {
+                // First try the authenticated user's primary account locale.
+                try {
+                    const user = await this.getCurrentUser();
+                    const primary = (0, languageUtils_1.getPrimaryLanguage)(user);
+                    if (primary) {
+                        return primary;
+                    }
+                }
+                catch {
+                    // Not authenticated or the profile fetch failed — fall through to the
+                    // locally stored preference below.
+                }
+                // Fall back to the locally stored locale preference.
+                const storage = await this.getStorage();
+                const storageKey = `${storageKeyPrefix}_language`;
+                const storedLanguage = await storage.getItem(storageKey);
+                if (storedLanguage) {
+                    return (0, languageUtils_1.normalizeLocale)(storedLanguage) ?? storedLanguage;
+                }
+                return null;
+            }
+            catch (error) {
+                logger_1.logger.warn('Failed to get current language', { component: 'OxyServices.language' }, error);
+                return null;
+            }
+        }
+        /**
+         * Get the current language with metadata (name, nativeName, etc.)
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns Language metadata object or null if not set
+         */
+        async getCurrentLanguageMetadata(storageKeyPrefix = 'oxy_session') {
+            const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
+            return (0, languageUtils_1.getLanguageMetadata)(languageCode);
+        }
+        /**
+         * Get the current language name (e.g., 'English')
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns Language name or null if not set
+         */
+        async getCurrentLanguageName(storageKeyPrefix = 'oxy_session') {
+            const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
+            if (!languageCode)
+                return null;
+            return (0, languageUtils_1.getLanguageName)(languageCode);
+        }
+        /**
+         * Get the current native language name (e.g., 'Español')
+         * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
+         * @returns Native language name or null if not set
+         */
+        async getCurrentNativeLanguageName(storageKeyPrefix = 'oxy_session') {
+            const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
+            if (!languageCode)
+                return null;
+            return (0, languageUtils_1.getNativeLanguageName)(languageCode);
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.links.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesLinksMixin = OxyServicesLinksMixin;
+const apiUtils_1 = require("../utils/apiUtils");
+/**
+ * Maximum number of URLs sent per `POST /links/previews` request. Matches the
+ * server-side batch cap (`linkPreviewBatchRequestSchema`'s `.max(50)`); larger
+ * inputs are split into multiple chunked calls and the result maps merged,
+ * mirroring how `getUsersByIds` chunks at 100.
+ */
+const LINK_PREVIEWS_CHUNK_SIZE = 50;
+function OxyServicesLinksMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Resolve a single link preview via `GET /links/preview?url=<encoded>&wait=0|1`.
+         *
+         * @param url - The URL to unfurl. Sent percent-encoded in the query string.
+         * @param opts.wait - When `true`, asks the server to resolve synchronously
+         *   (`wait=1`) instead of returning a `'pending'` placeholder for a
+         *   first-seen URL. Defaults to `false` (`wait=0`).
+         *
+         * Not cached at the SDK layer: a `'pending'` result can become `'resolved'`
+         * on a later read, so caching here would serve the stale placeholder.
+         */
+        async getLinkPreview(url, opts) {
+            try {
+                const path = (0, apiUtils_1.buildUrl)('/links/preview', { url, wait: opts?.wait ? 1 : 0 });
+                return await this.makeRequest('GET', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Resolve multiple link previews via `POST /links/previews` (body `{ urls }`).
+         *
+         * Inputs are de-duplicated and split into chunks of {@link LINK_PREVIEWS_CHUNK_SIZE}
+         * (the server-side cap). Chunks run concurrently and their result maps are
+         * merged into a single result keyed by the REQUESTED url (the exact string
+         * passed in `urls`) — matching the batch contract — so a caller can always
+         * look its own input back up.
+         *
+         * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
+         * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
+         * already the `Record<url, LinkPreview>` map — merge it directly.
+         *
+         * An empty / whitespace-only input resolves immediately with `{}` and
+         * performs no network call. A failure in any chunk surfaces (via
+         * `handleError`) rather than being swallowed.
+         */
+        async getLinkPreviews(urls) {
+            const uniqueUrls = Array.from(new Set(urls.filter((u) => typeof u === 'string' && u.trim().length > 0)));
+            if (uniqueUrls.length === 0) {
+                return {};
+            }
+            const chunks = [];
+            for (let i = 0; i < uniqueUrls.length; i += LINK_PREVIEWS_CHUNK_SIZE) {
+                chunks.push(uniqueUrls.slice(i, i + LINK_PREVIEWS_CHUNK_SIZE));
+            }
+            try {
+                const responses = await Promise.all(chunks.map((chunk) => this.makeRequest('POST', '/links/previews', { urls: chunk }, { cache: false })));
+                return responses.reduce((merged, response) => Object.assign(merged, response ?? {}), {});
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.location.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesLocationMixin = OxyServicesLocationMixin;
+function OxyServicesLocationMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Update user location
+         * @param latitude - Latitude coordinate
+         * @param longitude - Longitude coordinate
+         * @returns Location update result
+         */
+        async updateLocation(latitude, longitude) {
+            try {
+                return await this.makeRequest('POST', '/location', {
+                    latitude,
+                    longitude
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get nearby users
+         * @param radius - Optional search radius in meters
+         * @returns Array of nearby users
+         */
+        async getNearbyUsers(radius) {
+            try {
+                const params = radius ? { radius } : undefined;
+                return await this.makeRequest('GET', '/location/nearby', params, {
+                    cache: false, // Don't cache location data - always get fresh data
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.nodes.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesNodesMixin = OxyServicesNodesMixin;
+const signatureService_1 = require("../crypto/signatureService");
+const OxyServices_identity_1 = require("./OxyServices.identity");
+const mixinHelpers_1 = require("./mixinHelpers");
+/**
+ * AtProto-style collection (NSID) for a user-node registration record — matches
+ * the server's `NODE_COLLECTION`. A user has exactly one node, so the record is
+ * keyed by the constant {@link NODE_RKEY} (last-writer-wins): re-registering
+ * over-writes the single `self` record rather than appending a second node.
+ */
+const NODE_COLLECTION = 'app.oxy.node';
+/**
+ * The AtProto-style record key for the single node registration — matches the
+ * server's `NODE_RKEY`. Constant (`'self'`) because a user has one node.
+ */
+const NODE_RKEY = 'self';
+/**
+ * Cache-key prefix of every node read (`GET /nodes/me`). Swept after a
+ * register / revoke / managed-provision so a re-read reflects the new node
+ * (or its absence) instead of a stale cached one. The identity tag is a key
+ * SUFFIX, so this prefix invalidates the resource for every cached identity.
+ */
+const NODES_CACHE_PREFIX = 'GET:/nodes/';
+/**
+ * Cache-key prefix of the current user's `GET /users/me`. Swept alongside the
+ * node caches because the user's derived DID document embeds an `#oxy-node`
+ * service entry derived from the node row, so registering / revoking / managing
+ * a node changes user-facing identity state.
+ */
+const USERS_ME_CACHE_PREFIX = 'GET:/users/me';
+function OxyServicesNodesMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Register (or re-register) the caller's SELF-HOSTED personal data node.
+         *
+         * Builds the `{ endpoint, nodePublicKey, mode }` node record, signs a v2
+         * envelope on the caller's own per-subject hash chain (fetching the current
+         * chain head first so `seq`/`prev` are never stale), and publishes it through
+         * the EXISTING `POST /identity/records` path — which verifies the signature
+         * and materializes the operational node cache as a side effect. The signed
+         * record (not this call) is the authority; re-registering over-writes the
+         * single `self` record (last-writer-wins).
+         *
+         * NATIVE-ONLY: signs with the on-device identity key (throws on web / when no
+         * identity or no authenticated user — the guard fires before any network).
+         * `mode` defaults to `'pull'`. After a successful publish the node + `/users/me`
+         * GET caches are swept, then the freshly-materialized status is returned.
+         *
+         * Throws if the chain record stored but the server skipped materialization
+         * (e.g. a malformed endpoint the server rejected) — an unexpected state rather
+         * than a silent `null`.
+         *
+         * @param input - The node's endpoint, public key, and optional transport mode.
+         */
+        async registerNode(input) {
+            try {
+                const userId = this.getCurrentUserId();
+                if (!userId) {
+                    throw new Error('No authenticated user — sign in before registering a node.');
+                }
+                const subject = (0, OxyServices_identity_1.buildUserDid)(userId);
+                const record = {
+                    endpoint: input.endpoint,
+                    nodePublicKey: input.nodePublicKey,
+                    mode: input.mode ?? 'pull',
+                };
+                // Fetch the caller's chain head fresh (uncached) so seq/prev are correct
+                // → no bad_seq / chain_fork — exactly as the identity/civic signers do.
+                const head = await this.makeRequest('GET', `/identity/records/${encodeURIComponent(userId)}/chain/head`, undefined, { cache: false });
+                const envelope = await signatureService_1.SignatureService.signRecordV2('node', subject, record, {
+                    seq: head.seq + 1,
+                    prev: head.headRecordId,
+                    collection: NODE_COLLECTION,
+                    rkey: NODE_RKEY,
+                });
+                await this.makeRequest('POST', '/identity/records', envelope, { cache: false });
+                this._sweepNodeCaches();
+                const node = await this.getMyNode();
+                if (!node) {
+                    throw new Error('Node registration stored but the node could not be materialized.');
+                }
+                return node;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Read the caller's registered node status (`GET /nodes/me`), or `null` when
+         * the caller has no node. Auth required; short-TTL cached (the liveness badge
+         * is background-maintained) and swept after the caller's own
+         * register / revoke / managed-provision.
+         */
+        async getMyNode() {
+            try {
+                const res = await this.makeRequest('GET', '/nodes/me', undefined, { cache: true, cacheTTL: mixinHelpers_1.CACHE_TIMES.SHORT });
+                return res.node ?? null;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Revoke the caller's node registration (`DELETE /nodes/me`). The node flips
+         * to `revoked` server-side (leaving the DID document and liveness sweeps).
+         * Auth required; the node + `/users/me` GET caches are swept on success.
+         *
+         * Maps the server's `{ success }` to the SDK's `{ revoked }` semantic.
+         */
+        async removeMyNode() {
+            try {
+                const res = await this.makeRequest('DELETE', '/nodes/me', undefined, { cache: false });
+                this._sweepNodeCaches();
+                return { revoked: res.success === true };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Provision (or refresh) an Oxy-operated MANAGED vault for the caller
+         * (`POST /nodes/managed`) — the "Create your vault" convenience for
+         * non-technical users. Oxy custodial-signs the node registration onto the
+         * caller's chain and returns the materialized node (`managed:true,
+         * controller:'oxy'`). Idempotent server-side. Auth required; the owner id is
+         * resolved from the session, never the body. The node + `/users/me` GET caches
+         * are swept on success.
+         */
+        async provisionManagedVault() {
+            try {
+                const res = await this.makeRequest('POST', '/nodes/managed', undefined, { cache: false });
+                this._sweepNodeCaches();
+                return res.node;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Send an ingest HINT that a user's node has new records
+         * (`POST /nodes/ingest/notify/:userId`). Unauthenticated by design and
+         * fire-and-forget on the server (it only schedules a background re-pull of the
+         * named user's OWN node, then fully re-verifies — a notify can never inject
+         * data), so this resolves once the 202 hint is accepted and returns nothing.
+         *
+         * @param userId - The user whose node may have new records. URL-encoded.
+         */
+        async notifyNodeIngest(userId) {
+            try {
+                await this.makeRequest('POST', `/nodes/ingest/notify/${encodeURIComponent(userId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Sweep the GET caches a node mutation invalidates: every node read
+         * (`GET:/nodes/`) so a re-read reflects the new node / its absence, and
+         * `/users/me` because the user's derived DID document embeds an `#oxy-node`
+         * service entry that changes on register / revoke / manage. Public rather
+         * than `private` because mixins compose into an exported anonymous class
+         * where TypeScript cannot represent a private member in the emitted
+         * declaration file (TS4094) — mirrors the civic / identity cache sweepers.
+         */
+        _sweepNodeCaches() {
+            this.clearCacheByPrefix(NODES_CACHE_PREFIX);
+            this.clearCacheByPrefix(USERS_ME_CACHE_PREFIX);
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.notifications.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesNotificationsMixin = OxyServicesNotificationsMixin;
+/**
+ * Shape of an Expo push token: `ExponentPushToken[…]` (what
+ * `getExpoPushTokenAsync()` returns today) or the equivalent `ExpoPushToken[…]`
+ * spelling. Deliberately plain ASCII — `@oxy.so/core` ships to Hermes, where
+ * Unicode property escapes throw at runtime.
+ */
+const EXPO_PUSH_TOKEN_PATTERN = /^Expo(nent)?PushToken\[[^[\]\s]+\]$/;
+function OxyServicesNotificationsMixin(Base) {
+    return class extends Base {
+        /**
+         * Register this installation's **Expo** push token for the authenticated
+         * identity (`POST /notifications/push-token`, bearer required).
+         *
+         * Idempotent server-side: re-registering the same token for the same
+         * identity refreshes the existing row rather than creating a duplicate, so
+         * callers can safely re-register on every cold boot.
+         *
+         * @throws When `expoPushToken` is not an Expo push token — a raw APNs/FCM
+         *   device token fails here rather than becoming a silently undeliverable
+         *   registration.
+         */
+        async registerPushToken(input) {
+            try {
+                if (!EXPO_PUSH_TOKEN_PATTERN.test(input.expoPushToken)) {
+                    throw new Error('registerPushToken expects an Expo push token ("ExponentPushToken[...]", from getExpoPushTokenAsync). ' +
+                        'A raw APNs/FCM device token from getDevicePushTokenAsync cannot be delivered to.');
+                }
+                await this.makeRequest('POST', '/notifications/push-token', {
+                    token: input.expoPushToken,
+                    platform: input.platform,
+                    // Omitted entirely when absent so the body stays exactly what the
+                    // endpoint has always received (the server reads presence).
+                    ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+                    ...(input.clientId ? { clientId: input.clientId } : {}),
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Retire an **Expo** push token for the authenticated identity
+         * (`DELETE /notifications/push-token`, bearer required).
+         *
+         * Call it when the user turns notifications off, when the vault identity is
+         * replaced, and on sign-out — otherwise the installation keeps receiving
+         * approval requests for an identity it no longer holds.
+         *
+         * @param expoPushToken - The exact token previously registered.
+         */
+        async unregisterPushToken(expoPushToken) {
+            try {
+                await this.makeRequest('DELETE', '/notifications/push-token', { token: expoPushToken }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}