@oxy.so/core 1.18.0 → 3.0.0

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

@@ -0,0 +1,77 @@
+/**
+ * `oxy.notifications` — the signed-in user's in-app inbox, and this
+ * installation's push token.
+ *
+ * ## Push tokens are EXPO push tokens
+ *
+ * `registerPushToken` takes the token `Notifications.getExpoPushTokenAsync()`
+ * returns — the `ExponentPushToken[…]` handle — because the server delivers
+ * through Expo's push service, which only accepts that form. A raw APNs/FCM
+ * token from `getDevicePushTokenAsync()` registers "successfully" and then
+ * every push silently fails at delivery, so it is rejected here, before any
+ * request. Acquiring the token (permission prompt, `expo-notifications`) is the
+ * app's job — `@oxy.so/core` never imports an `expo-*` module.
+ *
+ * Creating a notification is a service-token call: `OxyServer`'s
+ * `notifications.create` (`@oxy.so/core/server`).
+ */
+import type { OxyContext } from '../client/context';
+import type { Notification, NotificationPage } from '../models/interfaces';
+/** Platform a push token was minted on; the server rejects any other value. */
+export type PushTokenPlatform = 'ios' | 'android' | 'web';
+/** Input for {@link NotificationsApi.registerPushToken}. */
+export interface RegisterPushTokenInput {
+    /**
+     * The **Expo push token** for this installation (`ExponentPushToken[…]`).
+     * NOT the raw APNs/FCM token from `getDevicePushTokenAsync()`.
+     */
+    expoPushToken: string;
+    platform: PushTokenPlatform;
+    /**
+     * The device-first `deviceId` this installation is registered under, so the
+     * server can retire the token when that device session goes away.
+     */
+    deviceId?: string;
+    /**
+     * The registered OAuth client id (`oxy_dk_…`) of WHICH application this
+     * installation is — what lets a "Sign in with Oxy" request reach a known
+     * Commons installation instead of every token the identity owns.
+     */
+    clientId?: string;
+}
+export declare class NotificationsApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /** One page of the inbox, newest first, with the unread count across all pages. */
+    list(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<NotificationPage>;
+    /** How many notifications are unread. */
+    unreadCount(): Promise<number>;
+    /**
+     * Mark one notification read and return it as stored. Scoped to the recipient
+     * server-side, so it is also the authoritative read by id: a foreign or
+     * unknown id 404s.
+     */
+    markRead(notificationId: string): Promise<Notification>;
+    /** Mark every notification read. */
+    markAllRead(): Promise<void>;
+    /** Delete one notification. */
+    delete(notificationId: string): Promise<void>;
+    /**
+     * Register this installation's Expo push token for the signed-in identity
+     * (`POST /notifications/push-token`). Idempotent server-side, so it is safe to
+     * call on every cold boot.
+     *
+     * @throws When `expoPushToken` is not an Expo push token.
+     */
+    registerPushToken(input: RegisterPushTokenInput): Promise<void>;
+    /**
+     * Retire a push token (`DELETE /notifications/push-token`). Call it when the
+     * user turns notifications off, when the identity is replaced, and on
+     * sign-out — or the installation keeps receiving requests for an identity it
+     * no longer holds.
+     */
+    unregisterPushToken(expoPushToken: string): Promise<void>;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * `oxy.privacy` — privacy settings, blocked and restricted users.
+ */
+import type { BlockedUser, PrivacySettings, RestrictedUser } from '../models/interfaces';
+import type { OxyContext } from '../client/context';
+export declare class PrivacyApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** A user's privacy settings (default: the signed-in user's). */
+    settings(userId?: string): Promise<PrivacySettings>;
+    /** Update privacy settings (default: the signed-in user's). */
+    updateSettings(settings: Partial<PrivacySettings>, userId?: string): Promise<PrivacySettings>;
+    /** The signed-in user's blocked users. */
+    blocked(): Promise<BlockedUser[]>;
+    /** Block a user. */
+    block(userId: string): Promise<{
+        message: string;
+    }>;
+    /** Unblock a user. */
+    unblock(userId: string): Promise<{
+        message: string;
+    }>;
+    /** Whether the signed-in user blocked `userId`. `false` when the list cannot be read. */
+    isBlocked(userId: string): Promise<boolean>;
+    /** The signed-in user's restricted users. */
+    restricted(): Promise<RestrictedUser[]>;
+    /** Restrict a user: limit their interactions without blocking them. */
+    restrict(userId: string): Promise<{
+        message: string;
+    }>;
+    /** Lift a restriction. */
+    unrestrict(userId: string): Promise<{
+        message: string;
+    }>;
+    /** Whether the signed-in user restricted `userId`. `false` when the list cannot be read. */
+    isRestricted(userId: string): Promise<boolean>;
+    /**
+     * A block or restriction changes the list AND the viewer's consolidated graph
+     * (`blockedIds` / `restrictedIds` in `GET /users/me/graph`); both go.
+     */
+    private invalidate;
+    private resolveUserId;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * `oxy.reputation` — Oxy Trust reputation, read-only.
+ *
+ * People only READ reputation here. Points come from the applications that
+ * observed an action (`OxyServer.reputation.award`, service token), under rules
+ * fixed in code. Nobody — staff included — edits a person's standing by hand.
+ *
+ * Every type is owned by `@oxy.so/contracts`; import them from there.
+ */
+import type { ReputationBalance, ReputationBalanceView, ReputationInfluenceContext, ReputationInfluenceResult, ReputationLeaderboardEntry, ReputationRule, ReputationTransaction } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+/** Cache-key prefix of every cached `GET /reputation/...` response. */
+export declare const REPUTATION_CACHE_PREFIX = "GET:/reputation/";
+export interface ReputationPage {
+    limit?: number;
+    offset?: number;
+}
+export declare class ReputationApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /**
+     * The SIGNED-IN user's balance, in full (`breakdown`, `influence`,
+     * `reliability`). Throws when not signed in, or when the server answered with
+     * the public view (the request was not authenticated as the subject).
+     */
+    balance(): Promise<ReputationBalance>;
+    /**
+     * ANY user's balance, in whichever view the server serves the caller: a third
+     * party gets only `userId`, `total` and `trustTier`. Narrow with
+     * `isFullReputationBalance` before reading the private blocks.
+     * @param userId - The subject's `_id` or publicKey.
+     */
+    balance(userId: string): Promise<ReputationBalanceView>;
+    /** The leaderboard, by lifetime total, descending. */
+    leaderboard(page?: ReputationPage): Promise<ReputationLeaderboardEntry[]>;
+    /** The enabled rules: what earns and what costs reputation. */
+    rules(): Promise<ReputationRule[]>;
+    /**
+     * A user's ledger, newest first (default: the signed-in user's). Auth required.
+     * @param userId - The subject's `_id` or publicKey.
+     */
+    transactions(userId?: string, page?: ReputationPage): Promise<ReputationTransaction[]>;
+    /**
+     * A user's capped influence weight for one context (default: the signed-in
+     * user's). Auth required.
+     * @param context - The weight axis (server default: `default`).
+     */
+    influence(userId?: string, context?: ReputationInfluenceContext): Promise<ReputationInfluenceResult>;
+    protected resolveUserId(userId?: string): string;
+}

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

@@ -0,0 +1,85 @@
+import type { DeviceProof } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import type { ClientSession } from '../models/session';
+import type { User } from '../models/interfaces';
+/**
+ * Reads the device credential this client holds, if any — `{ deviceId,
+ * deviceSecret }` from the provider's auth store. See
+ * {@link SessionApi.setDeviceCredentialProvider}.
+ */
+export type DeviceCredentialProvider = () => Promise<DeviceProof | null> | DeviceProof | null;
+export interface SessionValidation {
+    valid: boolean;
+    expiresAt: string;
+    lastActivity: string;
+    user: User;
+    sessionId?: string;
+    source?: string;
+}
+export declare class SessionApi {
+    private readonly ctx;
+    private deviceCredentialProvider;
+    private decodedFor;
+    private decoded;
+    constructor(ctx: OxyContext);
+    /** The current access token, or `null` when signed out. */
+    get accessToken(): string | null;
+    /** Whether an access token is held. Does not ask the server; see `validateToken`. */
+    get isAuthenticated(): boolean;
+    /** The signed-in user's id, from the access token; `null` when signed out. */
+    get userId(): string | null;
+    /**
+     * The access token's `exp` in SECONDS since the epoch (the raw JWT unit), or
+     * `null` when there is no token or it carries no numeric `exp`. Powers the
+     * proactive refresh timer in `@oxy.so/services`.
+     */
+    get accessTokenExpiry(): number | null;
+    /** Plant an access token (e.g. one a sign-in returned). */
+    setAccessToken(accessToken: string): void;
+    /**
+     * Forget the token and end the local session: a re-mint already in flight
+     * plants nothing, and none runs until a token is set again.
+     */
+    clear(): void;
+    /**
+     * Subscribe to access-token changes — `setAccessToken`, `clear`, a silent
+     * refresh, the 401-driven clear. The listener gets the new token, or `null`.
+     * Returns the unsubscribe.
+     */
+    onChange(listener: (accessToken: string | null) => void): () => void;
+    /**
+     * Resolve `true` as soon as a token is held, or `false` after `timeoutMs`.
+     * Event-driven: no polling.
+     */
+    waitForAuth(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Tell this client how to read the device credential it holds, so a sign-in
+     * can PROVE the device (ADR 0029 D2): every sign-in in `oxy.auth` then sends
+     * it as `device`, and the server puts the new session on that device — the
+     * browser's shared one, which every Oxy app holding it sees at once.
+     *
+     * `OxyProvider` wires this from its auth store; nothing else needs to.
+     * Returns a disposer that clears it (only if still installed).
+     */
+    setDeviceCredentialProvider(provider: DeviceCredentialProvider | null): () => void;
+    /**
+     * The device proof a sign-in should carry, or `null`. Never throws: a store
+     * that cannot be read only means the sign-in gets its own device.
+     */
+    readDeviceProof(): Promise<DeviceProof | null>;
+    /** Ask the server whether the current access token is valid. */
+    validateToken(): Promise<boolean>;
+    /** Validate a session by id and return it with its user. */
+    validate(sessionId: string, options?: {
+        deviceFingerprint?: string;
+        useHeaderValidation?: boolean;
+    }): Promise<SessionValidation>;
+    /** The sessions that belong with `sessionId` (same account set). */
+    list(sessionId: string): Promise<ClientSession[]>;
+    /** Sign out `sessionId`, or — with `targetSessionId` — one of the sessions beside it. */
+    logout(sessionId: string, targetSessionId?: string): Promise<void>;
+    /** Sign out every session beside `sessionId`, and it. */
+    logoutAll(sessionId: string): Promise<void>;
+    /** Decoded claims of the current token, memoised per token string. */
+    private claims;
+}

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

@@ -0,0 +1,278 @@
+/**
+ * `oxy.store` — the Oxy app store: the public storefront (`/store`), the
+ * reviews people write there, and the listing a publisher edits for an
+ * application they own (`/applications/:appId/listing`).
+ *
+ * Separate from `oxy.apps` even though the publisher's routes hang off an
+ * application: `apps` answers "may this program act for this person?", and this
+ * answers "should this person choose it?". Turn the store off and OAuth still
+ * works — the store is a module over the platform rather than part of it.
+ *
+ * A listing carries no name, icon or legal links: the application already holds
+ * them and the storefront joins them in. A rating is computed from the visible
+ * reviews on every read rather than stored, so a hidden review stops counting
+ * the moment it is hidden. Reference listings by their `slug` in the storefront
+ * (it is what every link carries) and applications by their `_id` in the
+ * publisher's calls.
+ */
+import type { OxyContext } from '../client/context';
+/** A shelf on the storefront. */
+export interface StoreCategory {
+    /** The public identifier a link carries. Never the row id. */
+    slug: string;
+    /** What a person reads. Never derived from the slug at render time. */
+    label: string;
+    description?: string | null;
+}
+/** The rating of an app, computed from its visible reviews. */
+export interface StoreRating {
+    /** Rounded to one decimal, or `null` when nobody has reviewed it — never 0. */
+    average: number | null;
+    count: number;
+}
+/** An app as a card on the storefront: what a listing page needs, and no more. */
+export interface StoreListingSummary {
+    slug: string;
+    /** From the APPLICATION, joined in — the listing keeps no copy. */
+    name: string;
+    tagline: string | null;
+    /** A file id for the app's icon, resolved through the usual image resolver. */
+    icon: string | null;
+    category: StoreCategory | null;
+    rating: StoreRating;
+}
+/** A store page in full. */
+export interface StoreListingDetail extends StoreListingSummary {
+    description: string | null;
+    /** These four come from the application; the consent screen shows the same values. */
+    websiteUrl: string | null;
+    privacyPolicyUrl: string | null;
+    termsUrl: string | null;
+    supportUrl: string | null;
+    supportEmail: string | null;
+    publishedAt: string | null;
+    screenshots: StoreScreenshot[];
+    /** How many visible reviews gave each of 1..5. Absent keys are zero. */
+    ratingBreakdown: Record<number, number>;
+}
+/** Which frame a screenshot was taken in. The store groups by it on the page. */
+export type StoreScreenshotPlatform = 'phone' | 'tablet' | 'desktop' | 'web';
+export interface StoreScreenshot {
+    id: string;
+    /** The uploaded asset's file id. Upload through the assets surface first. */
+    fileId: string;
+    platform: StoreScreenshotPlatform;
+    caption: string | null;
+    position: number;
+}
+/** Somebody's review, as it appears on a store page. */
+export interface StoreReview {
+    id: string;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    createdAt: string;
+    author: {
+        id: string;
+        username: string | null;
+    };
+    /** The publisher's answer, when there is one. */
+    reply: {
+        body: string;
+        createdAt: string;
+    } | null;
+    /**
+     * Whether this author has authorized the application, read from their grant
+     * at request time rather than stored on the review.
+     *
+     * It is not a claim that they still use it, and it is `false` for a
+     * first-party app nobody has to consent to — so render its absence as nothing
+     * at all rather than as a demotion.
+     */
+    authorUsesApp: boolean;
+}
+/** A review as its own author sees it, whatever its moderation state. */
+export interface StoreOwnReview {
+    id: string;
+    rating: number;
+    title: string | null;
+    body: string | null;
+    /** An author is told when their review is hidden; the public list is not. */
+    status: 'visible' | 'hidden' | 'flagged' | 'removed';
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a person submits about an app. One review each; writing again replaces it. */
+export interface WriteStoreReviewInput {
+    /** Whole stars, 1 to 5. The database enforces the bound too. */
+    rating: number;
+    title?: string | null;
+    body?: string | null;
+}
+/** Where a listing is in its life. `pending_review` is the STORE's review of the page. */
+export type StoreListingStatus = 'draft' | 'pending_review' | 'published' | 'rejected';
+/** A listing as its publisher sees it: whatever state it is in. */
+export interface PublisherListing {
+    id: string;
+    applicationId: string;
+    slug: string;
+    tagline: string | null;
+    description: string | null;
+    category: StoreCategory | null;
+    supportUrl: string | null;
+    supportEmail: string | null;
+    status: StoreListingStatus;
+    publishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * The whole page, not a patch: sending everything is what makes "clear the
+ * tagline" expressible at all.
+ *
+ * `status` is absent on purpose. Publishing is the store's decision and has its
+ * own calls, so a publisher cannot publish themselves by putting a field in a
+ * body.
+ */
+export interface WriteListingInput {
+    /** Lowercase letters, digits and single hyphens. What every link carries. */
+    slug: string;
+    tagline?: string | null;
+    description?: string | null;
+    /** A category SLUG, never its id. */
+    categorySlug?: string | null;
+    supportUrl?: string | null;
+    supportEmail?: string | null;
+}
+export interface AddScreenshotInput {
+    /** An already-uploaded image. Must be live, an image, and yours to publish. */
+    fileId: string;
+    platform?: StoreScreenshotPlatform;
+    caption?: string | null;
+}
+export interface UpdateScreenshotInput {
+    platform?: StoreScreenshotPlatform;
+    caption?: string | null;
+}
+/**
+ * One page of a paginated store read.
+ *
+ * `hasMore` comes from the API rather than being derived here, so a caller that
+ * pages does not have to re-implement the boundary the server already computed.
+ */
+export interface StorePage<T> {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+}
+/** Options for paging the storefront and the reviews under an app. */
+export interface StorePageOptions {
+    limit?: number;
+    offset?: number;
+}
+export interface StoreReviewsOptions extends StorePageOptions {
+    /** Newest first by default; `rating` surfaces the strongest opinions. */
+    sort?: 'recent' | 'rating';
+}
+/** `oxy.store.reviews` — what people say about an app, and the caller's own review. */
+export declare class StoreReviewsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** Visible reviews for a published app, each with the publisher's reply. */
+    list(slug: string, options?: StoreReviewsOptions): Promise<StorePage<StoreReview>>;
+    /** The caller's own review of an app, or `null` if they have not written one. */
+    mine(slug: string): Promise<StoreOwnReview | null>;
+    /**
+     * Write the caller's review, or replace what they said before.
+     *
+     * A person has one review per app, so this sets it rather than adding one.
+     * Rewriting does not clear a moderator's decision: a hidden review stays
+     * hidden when its author edits it.
+     */
+    write(slug: string, input: WriteStoreReviewInput): Promise<StoreOwnReview>;
+    /** Withdraw the caller's own review. A real delete — the words were theirs. */
+    deleteMine(slug: string): Promise<void>;
+}
+/** `oxy.store.listing.screenshots` — the pictures on a listing. */
+export declare class ListingScreenshotsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** Every picture on the listing, in the author's order. */
+    list(applicationId: string): Promise<StoreScreenshot[]>;
+    /**
+     * Attach an already-uploaded image, appended to the end.
+     *
+     * Upload through `oxy.assets` first; the store keeps a reference rather than
+     * a second copy of the asset pipeline. The file must be live, an image, and
+     * one the caller is entitled to.
+     */
+    add(applicationId: string, input: AddScreenshotInput): Promise<StoreScreenshot>;
+    /** Edit a picture's caption or the frame it was taken in. Order is `reorder`. */
+    update(applicationId: string, screenshotId: string, input: UpdateScreenshotInput): Promise<StoreScreenshot>;
+    /** Remove a picture. The uploaded file stays — it may be in use elsewhere. */
+    delete(applicationId: string, screenshotId: string): Promise<void>;
+    /**
+     * Set the order of every picture at once.
+     *
+     * Send EVERY id on the listing, exactly once, in the order they should
+     * appear. A partial list is rejected rather than applied: it would leave the
+     * pictures it omits at their old positions, interleaved with the new ones.
+     */
+    reorder(applicationId: string, screenshotIds: string[]): Promise<StoreScreenshot[]>;
+}
+/** `oxy.store.listing` — the page a publisher edits for an application they own. */
+export declare class StoreListingApi {
+    private readonly ctx;
+    /** The pictures on the listing. */
+    readonly screenshots: ListingScreenshotsApi;
+    constructor(ctx: OxyContext);
+    /** The application's store page in whatever state, or `null` if it has none. */
+    get(applicationId: string): Promise<PublisherListing | null>;
+    /**
+     * Create the page or replace its content. Never its status.
+     *
+     * Editing does not move a page: correcting a typo on a live listing leaves
+     * it live, and fixing a rejected one does not re-submit it.
+     */
+    write(applicationId: string, input: WriteListingInput): Promise<PublisherListing>;
+    /** Hand the page to the store for review. From a draft, or a rejected page once fixed. */
+    submit(applicationId: string): Promise<PublisherListing>;
+    /**
+     * Take the page down, or withdraw it from the queue.
+     *
+     * Back to a draft, never deleted: the slug, the words and the screenshots are
+     * the publisher's work, and the reviews were never the listing's to take with
+     * them.
+     */
+    unpublish(applicationId: string): Promise<PublisherListing>;
+}
+export declare class StoreApi {
+    private readonly ctx;
+    /** What people say about an app, and the caller's own review. */
+    readonly reviews: StoreReviewsApi;
+    /** The page a publisher edits for an application they own. */
+    readonly listing: StoreListingApi;
+    constructor(ctx: OxyContext);
+    /** The shelves, in the order the store curates them. */
+    categories(): Promise<StoreCategory[]>;
+    /**
+     * Published listings, newest first, optionally one shelf.
+     *
+     * An unknown category slug is an EMPTY shelf, not every app on the store —
+     * so a typo shows nothing rather than showing everything.
+     *
+     * @param options - `category` is a category slug; `limit` defaults to 24.
+     */
+    apps(options?: StorePageOptions & {
+        category?: string;
+    }): Promise<StorePage<StoreListingSummary>>;
+    /**
+     * One store page.
+     *
+     * A draft answers 404 exactly as an unknown slug does: whether an unpublished
+     * page exists under a name is not something a visitor learns.
+     *
+     * @param slug - The listing's public slug, not an application id.
+     */
+    app(slug: string): Promise<StoreListingDetail>;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * `oxy.topics` — the shared topic catalogue.
+ */
+import type { OxyContext } from '../client/context';
+import type { TopicData, TopicListResult, TopicTranslation } from '../models/Topic';
+export interface TopicListOptions {
+    type?: string;
+    q?: string;
+    limit?: number;
+    offset?: number;
+    locale?: string;
+}
+export declare class TopicsApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /** Topics, filtered and paginated; returns the page with `total`/`limit`/`offset`. */
+    list(options?: TopicListOptions): Promise<TopicListResult>;
+    /** Topics matching `query`. Never cached. */
+    search(query: string, limit?: number): Promise<TopicData[]>;
+    /** One topic by slug. */
+    get(slug: string): Promise<TopicData>;
+    /** The top-level categories, optionally translated. */
+    categories(locale?: string): Promise<TopicData[]>;
+    /** Resolve names to topics, creating the missing ones. Staff or service only. */
+    resolveNames(names: Array<{
+        name: string;
+        type: string;
+    }>): Promise<TopicData[]>;
+    /** Update a topic's description and translations. Staff or service only. */
+    update(slug: string, data: {
+        description?: string;
+        translations?: Record<string, TopicTranslation>;
+    }): Promise<TopicData>;
+}