@oxy.so/core 1.0.0

package/dist/types/mixins/OxyServices.devices.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Device Methods Mixin
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { DeviceLinkedSession, DeviceLinkedSessionLogoutResponse } from '../models/interfaces';
+export declare function OxyServicesDevicesMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Register a new device
+         * @param deviceData - Device information
+         * @returns Registered device object
+         */
+        registerDevice(deviceData: any): Promise<any>;
+        /**
+         * Get all devices for the current user
+         * @returns Array of user devices
+         */
+        getUserDevices(): Promise<any[]>;
+        /**
+         * Remove a device
+         * @param deviceId - The device ID to remove
+         */
+        removeDevice(deviceId: string): Promise<void>;
+        /**
+         * 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
+         */
+        getDeviceSessions(sessionId: string): Promise<DeviceLinkedSession[]>;
+        /**
+         * 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
+         */
+        logoutAllDeviceSessions(sessionId: string, deviceId?: string, excludeCurrent?: boolean): Promise<DeviceLinkedSessionLogoutResponse>;
+        /**
+         * Update device name
+         * @param sessionId - The session ID
+         * @param deviceName - New device name
+         * @returns Updated device object
+         */
+        updateDeviceName(sessionId: string, deviceName: string): Promise<any>;
+        /**
+         * Get security information
+         * @returns Security information object
+         */
+        getSecurityInfo(): Promise<{
+            recoveryEmail: string | null;
+        }>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.features.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Features Methods Mixin
+ *
+ * Provides methods for various features:
+ * - Feedback submission
+ * - Subscription plans
+ * - Saves/Collections
+ * - User history
+ * - FAQ
+ * - User stats
+ * - Achievements
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+export interface FeedbackPayload {
+    type: 'bug' | 'feature' | 'general' | 'support';
+    title: string;
+    description: string;
+    priority: 'low' | 'medium' | 'high' | 'critical';
+    category: string;
+    contactEmail?: string;
+    systemInfo?: {
+        platform: string;
+        version: string;
+        appVersion: string;
+        userId?: string;
+        username?: string;
+        timestamp: string;
+    };
+}
+export interface FeedbackResult {
+    id: string;
+    status: string;
+    createdAt: string;
+}
+export interface SubscriptionPlan {
+    id: string;
+    name: string;
+    description: string;
+    price: number;
+    currency: string;
+    interval: 'month' | 'year';
+    features: string[];
+}
+export interface SubscriptionResult {
+    subscriptionId: string;
+    status: string;
+    currentPeriodEnd: string;
+}
+export interface SavedItem {
+    id: string;
+    itemId: string;
+    itemType: string;
+    title: string;
+    createdAt: string;
+}
+export interface Collection {
+    id: string;
+    name: string;
+    description?: string;
+    itemCount: number;
+    createdAt: string;
+}
+export interface UserStats {
+    postCount: number;
+    commentCount: number;
+    followerCount: number;
+    followingCount: number;
+}
+export interface HistoryItem {
+    id: string;
+    type: string;
+    title: string;
+    timestamp: string;
+    metadata?: Record<string, any>;
+}
+export interface FAQ {
+    id: string;
+    question: string;
+    answer: string;
+    category: string;
+}
+export interface Achievement {
+    id: string;
+    name: string;
+    description: string;
+    icon: string;
+    unlockedAt?: string;
+}
+export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Submit user feedback
+         */
+        submitFeedback(payload: FeedbackPayload): Promise<FeedbackResult>;
+        /**
+         * Get available subscription plans
+         */
+        getSubscriptionPlans(): Promise<SubscriptionPlan[]>;
+        /**
+         * Get individual purchasable features
+         */
+        getIndividualFeatures(): Promise<any[]>;
+        /**
+         * Subscribe to a plan
+         */
+        subscribe(planId: string, paymentMethodId?: string): Promise<SubscriptionResult>;
+        /**
+         * Subscribe to an individual feature
+         */
+        subscribeToFeature(featureId: string, paymentMethodId?: string): Promise<SubscriptionResult>;
+        /**
+         * Cancel subscription
+         */
+        cancelSubscription(subscriptionId: string): Promise<void>;
+        /**
+         * Reactivate subscription
+         */
+        reactivateSubscription(subscriptionId: string): Promise<void>;
+        /**
+         * Get current user's subscription
+         */
+        getCurrentSubscription(): Promise<SubscriptionResult | null>;
+        /**
+         * Get user's saved items
+         */
+        getSavedItems(userId?: string): Promise<SavedItem[]>;
+        /**
+         * Get user's collections
+         */
+        getCollections(userId?: string): Promise<Collection[]>;
+        /**
+         * 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.
+         */
+        saveItem(itemId: string, itemType: string, collectionId?: string): Promise<SavedItem>;
+        /**
+         * Remove an item from saves.
+         *
+         * Busts the cached own saved-items list so the removed item is gone on
+         * the next read (see `saveItem`).
+         */
+        removeSavedItem(saveId: string): Promise<void>;
+        /**
+         * Create a collection.
+         *
+         * Busts the cached own collections list (`GET /collections`) so the new
+         * collection appears on the next read.
+         */
+        createCollection(name: string, description?: string): Promise<Collection>;
+        /**
+         * Delete a collection.
+         *
+         * Busts the cached own collections list so the deleted collection is
+         * gone on the next read (see `createCollection`).
+         */
+        deleteCollection(collectionId: string): Promise<void>;
+        /**
+         * Get user statistics
+         */
+        getUserStats(userId: string): Promise<UserStats>;
+        /**
+         * Get user history
+         */
+        getUserHistory(userId?: string, limit?: number, offset?: number): Promise<HistoryItem[]>;
+        /**
+         * 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.
+         */
+        clearUserHistory(): Promise<void>;
+        /**
+         * 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.
+         */
+        deleteHistoryItem(itemId: string): Promise<void>;
+        /**
+         * Get FAQs
+         */
+        getFAQs(category?: string): Promise<FAQ[]>;
+        /**
+         * Search FAQs
+         */
+        searchFAQs(query: string): Promise<FAQ[]>;
+        /**
+         * Get user achievements
+         */
+        getUserAchievements(userId?: string): Promise<Achievement[]>;
+        /**
+         * Get all available achievements
+         */
+        getAllAchievements(): Promise<Achievement[]>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.followGraph.d.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 type { FollowListPage, FollowMutation, FollowOptions, FollowStatus, UnfollowMutation } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesFollowGraphMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * 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.
+         */
+        followTarget(targetId: string, options?: FollowOptions): Promise<FollowMutation>;
+        /**
+         * 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.
+         */
+        unfollowTarget(relationshipId: string): Promise<UnfollowMutation>;
+        /**
+         * 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.
+         */
+        getFollowTargetStatus(targetId: string): Promise<FollowStatus>;
+        /**
+         * 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.
+         */
+        setFollowApplicationMode(relationshipId: string, mode: "enabled" | "disabled", applicationId?: string): Promise<{
+            ok: true;
+        }>;
+        /**
+         * 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.
+         */
+        restoreFollowInheritance(relationshipId: string, applicationId?: string): Promise<{
+            ok: true;
+        }>;
+        /**
+         * 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.
+         */
+        ensureFollowTarget(input: {
+            uri: string;
+            kind: string;
+            metadata?: Record<string, unknown>;
+            providerReference?: string;
+            localUserId?: string;
+        }): Promise<{
+            id: string;
+            uri: string;
+            kind: string;
+            created: boolean;
+        }>;
+        /**
+         * 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.
+         */
+        claimFollowNamespace(namespace: string): Promise<{
+            namespace: string;
+            created: boolean;
+        }>;
+        /**
+         * 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.
+         */
+        releaseFollowNamespace(namespace: string): Promise<{
+            namespace: string;
+            released: boolean;
+        }>;
+        /**
+         * 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.
+         */
+        registerFollowKind(input: {
+            kind: string;
+            label?: string;
+            capabilities?: {
+                verb?: "follow" | "subscribe" | "join" | "watch";
+                reverse?: "public" | "private" | "aggregate" | "unavailable";
+                federated?: boolean;
+            };
+        }): Promise<{
+            kind: string;
+            created: boolean;
+        }>;
+        /**
+         * 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.
+         */
+        listFollows(params?: {
+            kind?: string;
+            cursor?: string;
+            limit?: number;
+        }): Promise<FollowListPage>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;