@oxy.so/core 1.0.0

package/dist/esm/mixins/OxyServices.devices.js

@@ -0,0 +1,113 @@
+export function OxyServicesDevicesMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Register a new device
+         * @param deviceData - Device information
+         * @returns Registered device object
+         */
+        async registerDevice(deviceData) {
+            try {
+                return await this.makeRequest('POST', '/devices', deviceData, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get all devices for the current user
+         * @returns Array of user devices
+         */
+        async getUserDevices() {
+            try {
+                return await this.makeRequest('GET', '/devices', undefined, {
+                    cache: false, // Don't cache device list - always get fresh data
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Remove a device
+         * @param deviceId - The device ID to remove
+         */
+        async removeDevice(deviceId) {
+            try {
+                await this.makeRequest('DELETE', `/devices/${deviceId}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get device sessions for a given session ID
+         * Note: Not cached by default to ensure fresh data
+         * @param sessionId - The session ID
+         * @returns Array of device sessions
+         */
+        async getDeviceSessions(sessionId) {
+            try {
+                // Use makeRequest for consistent error handling and optional caching
+                // Cache disabled by default to ensure fresh session data
+                return await this.makeRequest('GET', `/session/device/sessions/${sessionId}`, undefined, {
+                    cache: false, // Don't cache sessions - always get fresh data
+                    deduplicate: true, // Deduplicate concurrent requests for same sessionId
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Logout all device sessions
+         * @param sessionId - The session ID
+         * @param deviceId - Optional device ID to target
+         * @param excludeCurrent - Whether to exclude the current session
+         * @returns Logout result
+         */
+        async logoutAllDeviceSessions(sessionId, deviceId, excludeCurrent) {
+            try {
+                const urlParams = {};
+                if (deviceId)
+                    urlParams.deviceId = deviceId;
+                if (excludeCurrent)
+                    urlParams.excludeCurrent = 'true';
+                return await this.makeRequest('POST', `/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Update device name
+         * @param sessionId - The session ID
+         * @param deviceName - New device name
+         * @returns Updated device object
+         */
+        async updateDeviceName(sessionId, deviceName) {
+            try {
+                return await this.makeRequest('PUT', `/session/device/name/${sessionId}`, { deviceName }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get security information
+         * @returns Security information object
+         */
+        async getSecurityInfo() {
+            try {
+                return await this.makeRequest('GET', '/devices/security', undefined, {
+                    cache: false,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.features.js

@@ -0,0 +1,332 @@
+import { CACHE_TIMES } from './mixinHelpers.js';
+export function OxyServicesFeaturesMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        // ==================
+        // FEEDBACK METHODS
+        // ==================
+        /**
+         * Submit user feedback
+         */
+        async submitFeedback(payload) {
+            try {
+                return await this.makeRequest('POST', '/feedback', payload, {
+                    cache: false,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // ==================
+        // SUBSCRIPTION METHODS
+        // ==================
+        /**
+         * Get available subscription plans
+         */
+        async getSubscriptionPlans() {
+            try {
+                return await this.makeRequest('GET', '/subscriptions/plans', undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.LONG,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get individual purchasable features
+         */
+        async getIndividualFeatures() {
+            try {
+                return await this.makeRequest('GET', '/subscriptions/features', undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.LONG,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Subscribe to a plan
+         */
+        async subscribe(planId, paymentMethodId) {
+            return this.withAuthRetry(async () => {
+                const result = await this.makeRequest('POST', '/subscriptions/subscribe', {
+                    planId,
+                    paymentMethodId,
+                }, { cache: false });
+                // The current subscription changed — bust its cached read so
+                // `getCurrentSubscription()` reflects the new plan immediately.
+                this.clearCacheEntry('GET:/subscriptions/current');
+                return result;
+            }, 'subscribe');
+        }
+        /**
+         * Subscribe to an individual feature
+         */
+        async subscribeToFeature(featureId, paymentMethodId) {
+            return this.withAuthRetry(async () => {
+                const result = await this.makeRequest('POST', '/subscriptions/features/subscribe', {
+                    featureId,
+                    paymentMethodId,
+                }, { cache: false });
+                this.clearCacheEntry('GET:/subscriptions/current');
+                return result;
+            }, 'subscribeToFeature');
+        }
+        /**
+         * Cancel subscription
+         */
+        async cancelSubscription(subscriptionId) {
+            return this.withAuthRetry(async () => {
+                await this.makeRequest('POST', `/subscriptions/${subscriptionId}/cancel`, undefined, {
+                    cache: false,
+                });
+                this.clearCacheEntry('GET:/subscriptions/current');
+            }, 'cancelSubscription');
+        }
+        /**
+         * Reactivate subscription
+         */
+        async reactivateSubscription(subscriptionId) {
+            return this.withAuthRetry(async () => {
+                await this.makeRequest('POST', `/subscriptions/${subscriptionId}/reactivate`, undefined, {
+                    cache: false,
+                });
+                this.clearCacheEntry('GET:/subscriptions/current');
+            }, 'reactivateSubscription');
+        }
+        /**
+         * Get current user's subscription
+         */
+        async getCurrentSubscription() {
+            return this.withAuthRetry(async () => {
+                try {
+                    return await this.makeRequest('GET', '/subscriptions/current', undefined, {
+                        cache: true,
+                        cacheTTL: CACHE_TIMES.SHORT,
+                    });
+                }
+                catch (error) {
+                    if (error.status === 404)
+                        return null;
+                    throw error;
+                }
+            }, 'getCurrentSubscription');
+        }
+        // ==================
+        // SAVES/COLLECTIONS
+        // ==================
+        /**
+         * Get user's saved items
+         */
+        async getSavedItems(userId) {
+            return this.withAuthRetry(async () => {
+                const endpoint = userId ? `/users/${userId}/saves` : '/saves';
+                return await this.makeRequest('GET', endpoint, undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.SHORT,
+                });
+            }, 'getSavedItems');
+        }
+        /**
+         * Get user's collections
+         */
+        async getCollections(userId) {
+            return this.withAuthRetry(async () => {
+                const endpoint = userId ? `/users/${userId}/collections` : '/collections';
+                return await this.makeRequest('GET', endpoint, undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.SHORT,
+                });
+            }, 'getCollections');
+        }
+        /**
+         * Save an item.
+         *
+         * Busts the cached own saved-items list (`GET /saves`, ~short TTL) so a
+         * follow-up `getSavedItems()` observes the new item. The `userId`-scoped
+         * variant (`/users/<id>/saves`) is another user's list and is not
+         * affected by the caller's own save.
+         */
+        async saveItem(itemId, itemType, collectionId) {
+            return this.withAuthRetry(async () => {
+                const result = await this.makeRequest('POST', '/saves', {
+                    itemId,
+                    itemType,
+                    collectionId,
+                }, { cache: false });
+                this.clearCacheEntry('GET:/saves');
+                return result;
+            }, 'saveItem');
+        }
+        /**
+         * Remove an item from saves.
+         *
+         * Busts the cached own saved-items list so the removed item is gone on
+         * the next read (see `saveItem`).
+         */
+        async removeSavedItem(saveId) {
+            return this.withAuthRetry(async () => {
+                await this.makeRequest('DELETE', `/saves/${saveId}`, undefined, { cache: false });
+                this.clearCacheEntry('GET:/saves');
+            }, 'removeSavedItem');
+        }
+        /**
+         * Create a collection.
+         *
+         * Busts the cached own collections list (`GET /collections`) so the new
+         * collection appears on the next read.
+         */
+        async createCollection(name, description) {
+            return this.withAuthRetry(async () => {
+                const result = await this.makeRequest('POST', '/collections', {
+                    name,
+                    description,
+                }, { cache: false });
+                this.clearCacheEntry('GET:/collections');
+                return result;
+            }, 'createCollection');
+        }
+        /**
+         * Delete a collection.
+         *
+         * Busts the cached own collections list so the deleted collection is
+         * gone on the next read (see `createCollection`).
+         */
+        async deleteCollection(collectionId) {
+            return this.withAuthRetry(async () => {
+                await this.makeRequest('DELETE', `/collections/${collectionId}`, undefined, { cache: false });
+                this.clearCacheEntry('GET:/collections');
+            }, 'deleteCollection');
+        }
+        // ==================
+        // USER STATS
+        // ==================
+        /**
+         * Get user statistics
+         */
+        async getUserStats(userId) {
+            try {
+                return await this.makeRequest('GET', `/users/${userId}/stats`, undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.MEDIUM,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // ==================
+        // HISTORY
+        // ==================
+        /**
+         * Get user history
+         */
+        async getUserHistory(userId, limit, offset) {
+            return this.withAuthRetry(async () => {
+                const params = {};
+                if (limit)
+                    params.limit = limit;
+                if (offset)
+                    params.offset = offset;
+                const endpoint = userId ? `/users/${userId}/history` : '/history';
+                return await this.makeRequest('GET', endpoint, params, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.SHORT,
+                });
+            }, 'getUserHistory');
+        }
+        /**
+         * Clear user history.
+         *
+         * `getUserHistory` caches per (limit, offset) page, so its cache key
+         * carries serialized params (`GET:/history` and `GET:/history:<params>`).
+         * A prefix sweep busts every cached page of the own history at once.
+         */
+        async clearUserHistory() {
+            return this.withAuthRetry(async () => {
+                await this.makeRequest('DELETE', '/history', undefined, { cache: false });
+                this.clearCacheByPrefix('GET:/history');
+            }, 'clearUserHistory');
+        }
+        /**
+         * Delete a history item.
+         *
+         * Busts every cached page of the own history (see `clearUserHistory`)
+         * so the removed item no longer appears on the next read.
+         */
+        async deleteHistoryItem(itemId) {
+            return this.withAuthRetry(async () => {
+                await this.makeRequest('DELETE', `/history/${itemId}`, undefined, { cache: false });
+                this.clearCacheByPrefix('GET:/history');
+            }, 'deleteHistoryItem');
+        }
+        // ==================
+        // FAQ
+        // ==================
+        /**
+         * Get FAQs
+         */
+        async getFAQs(category) {
+            try {
+                const params = category ? { category } : undefined;
+                return await this.makeRequest('GET', '/faqs', params, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.LONG,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Search FAQs
+         */
+        async searchFAQs(query) {
+            try {
+                return await this.makeRequest('GET', '/faqs/search', { query }, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.MEDIUM,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // ==================
+        // ACHIEVEMENTS
+        // ==================
+        /**
+         * Get user achievements
+         */
+        async getUserAchievements(userId) {
+            return this.withAuthRetry(async () => {
+                const endpoint = userId ? `/users/${userId}/achievements` : '/achievements';
+                return await this.makeRequest('GET', endpoint, undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.MEDIUM,
+                });
+            }, 'getUserAchievements');
+        }
+        /**
+         * Get all available achievements
+         */
+        async getAllAchievements() {
+            try {
+                return await this.makeRequest('GET', '/achievements/all', undefined, {
+                    cache: true,
+                    cacheTTL: CACHE_TIMES.LONG,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.followGraph.js

@@ -0,0 +1,218 @@
+/**
+ * Follow Graph Mixin (`/v2/follows`)
+ *
+ * The user-owned follow graph: one relationship per user and target, shared by
+ * every application, with per-application context on top. This is the SDK half
+ * of #809 and the replacement for the per-app follow endpoints each application
+ * grew for itself.
+ *
+ * ## Why this is not `followUser` with more parameters
+ *
+ * `followUser` answers "does A follow B" and nothing else. This answers "what
+ * does this user follow, anywhere, and which applications act on it" — a
+ * different question with a different owner. The legacy methods stay for the
+ * Mongo-backed social graph they were written for; new kinds (topics, stores,
+ * artists, channels) come here, and users will migrate behind an adapter rather
+ * than through a flag day.
+ *
+ * ## Caching
+ *
+ * Every method is `cache: false`. A follow status is exactly the shape that
+ * must never be served stale: the SDK's GET cache is identity-scoped but
+ * time-based, and a status cached across a write is the "follow reverts after
+ * navigating away and back" bug — which the legacy `followUser` had to fix with
+ * explicit invalidation. Not caching at this layer means an app's own store
+ * (React Query, Zustand) is the single cache authority, which is the rule the
+ * ecosystem already follows for anything written and read in the same session.
+ */
+import { buildUrl } from '../utils/apiUtils.js';
+export function OxyServicesFollowGraphMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Follow a target. Idempotent — following something already followed
+         * returns the same relationship with `created: false`.
+         *
+         * The follower and the acting application are BOTH derived server-side from
+         * the session. There is deliberately no parameter for either: a client that
+         * could name them could forge a follow on another user's behalf, or record
+         * one as coming from an application it is not.
+         *
+         * @param targetId - The registered target's id, not its URI. Registration is
+         *   a separate operation precisely so following cannot silently create
+         *   targets — a typo would otherwise become a permanent row nobody follows.
+         * @param options.expiresIn - Seconds until the follow lapses on its own. For
+         *   an event, a trial, a topic followed for a week. The server bounds it.
+         */
+        async followTarget(targetId, options) {
+            try {
+                return await this.makeRequest('PUT', `/v2/follows/${encodeURIComponent(targetId)}`, options?.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {}, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Unfollow everywhere.
+         *
+         * There is no "unfollow here" — that is `setFollowApplicationMode(...,
+         * 'disabled')`, and keeping the two distinct is the point of the design. An
+         * application that quietly turned a global unfollow into a local one would
+         * leave the user believing they had stopped following something they still
+         * follow everywhere else.
+         *
+         * Idempotent: `removed: false` when it was already gone, because the state
+         * the caller asked for is the state that holds.
+         */
+        async unfollowTarget(relationshipId) {
+            try {
+                return await this.makeRequest('DELETE', `/v2/follows/${encodeURIComponent(relationshipId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * The three-part status: globally, in this application, and in effect.
+         *
+         * Render `effectiveState` on the button and keep the other two for the
+         * explanation. A UI that collapses them cannot tell the user why a follow
+         * they can see in their list is not showing up in this app's feed.
+         */
+        async getFollowTargetStatus(targetId) {
+            try {
+                return await this.makeRequest('GET', `/v2/follows/${encodeURIComponent(targetId)}/status`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Turn a relationship off, or back on, in ONE application.
+         *
+         * Omit `applicationId` and it applies to the calling application, which is
+         * the only form an ordinary app should ever need. Naming a DIFFERENT
+         * application requires `follows:manage` server-side — acting on another
+         * app's behalf is exactly the cross-application authority this design
+         * otherwise refuses, so it is a distinct permission and not a parameter an
+         * app happens to fill in.
+         */
+        async setFollowApplicationMode(relationshipId, mode, applicationId) {
+            try {
+                return await this.makeRequest('PUT', `/v2/follows/${encodeURIComponent(relationshipId)}/context`, { mode, ...(applicationId ? { applicationId } : {}) }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Drop the override so this application follows the global relationship
+         * again. Distinct from setting `enabled`: inheriting means a later global
+         * change takes effect here, and an explicit `enabled` means it does not.
+         */
+        async restoreFollowInheritance(relationshipId, applicationId) {
+            try {
+                const path = buildUrl(`/v2/follows/${encodeURIComponent(relationshipId)}/context`, applicationId ? { applicationId } : {});
+                return await this.makeRequest('DELETE', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Resolve a target by canonical URI, registering it the first time anyone
+         * asks. The call an application makes on the way into a screen, before it
+         * can render a button.
+         *
+         * Idempotent on the URI, which is what makes two applications describing
+         * the same thing — the same fediverse actor, the same topic — arrive at ONE
+         * row, and therefore at one relationship per user rather than one per app.
+         *
+         * `metadata` is a display snapshot (name, handle, icon) and is refreshed
+         * only for the application that provides the target: a second application
+         * passing its own idea of the name would make the display flip depending on
+         * which app last looked.
+         */
+        async ensureFollowTarget(input) {
+            try {
+                return await this.makeRequest('POST', '/v2/follow-targets', input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Claim a namespace for the calling application. First come, and idempotent
+         * for the holder — an application that registers on every boot must not
+         * fail the second time.
+         */
+        async claimFollowNamespace(namespace) {
+            try {
+                return await this.makeRequest('POST', '/v2/follow-targets/namespaces', { namespace }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Release a namespace the calling application holds, when nothing is
+         registered inside it yet.
+         *
+         * Idempotent when the namespace is already unowned (`released: false`).
+         * Exists because claims are first-come and registration runs on boot — a
+         * development build with the wrong client id can bind a name permanently
+         * unless the holder can give it back.
+         */
+        async releaseFollowNamespace(namespace) {
+            try {
+                return await this.makeRequest('DELETE', `/v2/follow-targets/namespaces/${encodeURIComponent(namespace)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Declare what following a kind of thing MEANS: the verb clients render,
+         * whether reverse lookups are public, whether it federates.
+         *
+         * Declared once by the application that owns the concept, rather than
+         * passed per call site — otherwise two screens of one app can disagree
+         * about whether a store is followed or subscribed to.
+         */
+        async registerFollowKind(input) {
+            try {
+                return await this.makeRequest('POST', '/v2/follow-targets/kinds', input, {
+                    cache: false,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Everything the signed-in user follows, newest first.
+         *
+         * Owner-only by construction server-side — there is no parameter naming a
+         * user, so this cannot be pointed at somebody else's graph.
+         *
+         * Paginate by passing back `nextCursor`, never an offset: the list changes
+         * while it is being read, and an offset silently skips or repeats rows
+         * exactly when it does.
+         */
+        async listFollows(params) {
+            try {
+                const path = buildUrl('/v2/me/follows', {
+                    ...(params?.kind ? { kind: params.kind } : {}),
+                    ...(params?.cursor ? { cursor: params.cursor } : {}),
+                    ...(params?.limit ? { limit: params.limit } : {}),
+                });
+                return await this.makeRequest('GET', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}