@oxy.so/core 1.18.1 → 3.0.0

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

@@ -0,0 +1,433 @@
+/**
+ * `oxy.apps` — applications.
+ *
+ * Two unrelated surfaces share the word "app":
+ * - the applications an ACCOUNT owns and manages (`/applications`): the OAuth
+ *   clients, their credentials and usage — `apps.list/get/create/update/delete`,
+ *   `apps.credentials.*`, `apps.usage`. Access derives from the caller's
+ *   `AccountMember` on the owning account (`oxy.accounts`).
+ * - the THIRD-PARTY applications this user granted access to through the
+ *   consent flow — `apps.connected.*` — and the public identity of a requesting
+ *   application for consent screens — `apps.getPublic`.
+ *
+ * Reference applications by their `_id` (`applicationId`), credentials by their
+ * `credentialId`. A connected app is keyed by `applicationId`, never a
+ * credential/client id, so a grant and its revocation survive credential
+ * rotation.
+ */
+import type { OxyContext } from '../client/context';
+import type { AccountMember, AccountSuccessResult } from './accounts';
+/**
+ * Application classification. Set only by Oxy platform staff — never editable
+ * through the normal member-facing update path.
+ */
+export type ApplicationType = 'first_party' | 'third_party' | 'internal' | 'system';
+/** Lifecycle status of an application. */
+export type ApplicationStatus = 'active' | 'suspended' | 'deleted' | 'pending_review';
+/**
+ * Credential kind.
+ *
+ * The first three are OAuth clients: the `oxy_dk_…` `publicKey` is the
+ * `client_id`, and any secret is presented BESIDE it. `service` credentials
+ * additionally mint service tokens.
+ *
+ * `machine` is the OpenAI-SDK-compatible API key (issue #972 §2.3): its
+ * credential material is ONE `oxy_sk_…` bearer string returned in `token`
+ * exactly once on create/rotate, never in `secret`.
+ */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service' | 'machine';
+/** Deployment environment an application credential is scoped to. */
+export type ApplicationEnvironment = 'development' | 'staging' | 'production';
+/** Application credential lifecycle status. */
+export type ApplicationCredentialStatus = 'active' | 'deprecated' | 'revoked';
+/**
+ * Client-facing Application shape returned by the `/applications` API. An
+ * application is the OAuth client; it is OWNED by an account
+ * (`ownerAccountId`), and the caller's access derives from their `AccountMember`
+ * on that owning account (with inheritance).
+ */
+export interface Application {
+    _id: string;
+    name: string;
+    description?: string;
+    websiteUrl?: string;
+    /** Public privacy-policy URL, rendered as a legal link on the OAuth consent screen. */
+    privacyPolicyUrl?: string;
+    /** Public terms-of-service URL, rendered as a legal link on the OAuth consent screen. */
+    termsUrl?: string;
+    icon?: string;
+    type: ApplicationType;
+    status: ApplicationStatus;
+    isOfficial: boolean;
+    isInternal: boolean;
+    capabilities: string[];
+    redirectUris: string[];
+    scopes: string[];
+    webhookUrl?: string;
+    devWebhookUrl?: string;
+    createdByUserId: string;
+    /**
+     * The account that owns this application (account `_id`). Access to the
+     * application derives from the caller's `AccountMember` on this account, with
+     * inheritance up the account tree.
+     */
+    ownerAccountId: string;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * The caller's effective membership in the OWNING account (direct or
+     * inherited), embedded by the API on list/detail responses, or `null` when the
+     * caller has no membership. Use `callerMembership.permissions` to gate UI.
+     */
+    callerMembership?: AccountMember | null;
+}
+/**
+ * Client-facing ApplicationCredential shape (an application's OAuth client
+ * credentials). The raw secret is NEVER part of this shape — it is returned
+ * exactly once, separately, at creation/rotation.
+ */
+export interface ApplicationCredential {
+    _id: string;
+    applicationId: string;
+    name: string;
+    publicKey: string;
+    /**
+     * `oxy_sk_<id>` — the PUBLIC lookup half of a `machine` credential's bearer
+     * token, present only on that type. Safe to render: the secret half is 256
+     * bits that were shown exactly once and are never returned again.
+     */
+    tokenPrefix?: string;
+    type: ApplicationCredentialType;
+    environment: ApplicationEnvironment;
+    scopes: string[];
+    status: ApplicationCredentialStatus;
+    lastUsedAt?: string;
+    expiresAt?: string;
+    /**
+     * Audit link to the credential this one was rotated FROM. Populated on
+     * credentials created via rotation; absent on original credentials.
+     */
+    rotatedFromCredentialId?: string;
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input accepted by `apps.create`. Staff-only fields are not settable here. */
+export interface CreateApplicationInput {
+    name: string;
+    description?: string;
+    websiteUrl?: string;
+    /** Public privacy-policy URL (absolute `https://`). Shown on the OAuth consent screen. */
+    privacyPolicyUrl?: string;
+    /** Public terms-of-service URL (absolute `https://`). Shown on the OAuth consent screen. */
+    termsUrl?: string;
+    icon?: string;
+    redirectUris?: string[];
+    scopes?: string[];
+    /**
+     * Owning account `_id`. Omitted → the API defaults to the caller's personal
+     * account.
+     */
+    ownerAccountId?: string;
+}
+/** Input accepted by `apps.update`. Staff-only fields are not settable here. */
+export interface UpdateApplicationInput {
+    name?: string;
+    description?: string;
+    websiteUrl?: string;
+    /** Public privacy-policy URL (absolute `https://`, or `''` to clear). Shown on the OAuth consent screen. */
+    privacyPolicyUrl?: string;
+    /** Public terms-of-service URL (absolute `https://`, or `''` to clear). Shown on the OAuth consent screen. */
+    termsUrl?: string;
+    icon?: string;
+    redirectUris?: string[];
+    scopes?: string[];
+    webhookUrl?: string;
+    devWebhookUrl?: string;
+    status?: ApplicationStatus;
+}
+/** Input accepted by `apps.credentials.create`. */
+export interface CreateApplicationCredentialInput {
+    name: string;
+    type: ApplicationCredentialType;
+    environment: ApplicationEnvironment;
+    scopes?: string[];
+    /**
+     * Lifetime of a `machine` credential, in seconds — 60 to 730 days. Omit for a
+     * key that does not expire on its own.
+     *
+     * **`machine` only.** On every other credential type `expires_at` means the
+     * rotation grace deadline, so a caller setting it at creation would make a
+     * brand-new credential indistinguishable from a rotated one. The server
+     * REJECTS it for those types rather than ignoring it, so sending it with the
+     * wrong `type` is a 400, not a silently dropped field.
+     */
+    expiresInSeconds?: number;
+}
+/** Input accepted by `apps.credentials.rotate`. */
+export interface RotateApplicationCredentialInput {
+    /**
+     * How long the superseded `machine` token keeps working, in seconds — 1 to 30
+     * days. Omitting it revokes the previous token the instant the replacement is
+     * minted, which is the safe default for a leaked key.
+     *
+     * **`machine` only, and opt-in.** `confidential`/`service` credentials always
+     * retire on the platform's fixed seven-day grace and the server REJECTS this
+     * field for them, so their contract is unchanged.
+     */
+    graceSeconds?: number;
+}
+/**
+ * Result of creating an application credential — credential material is returned
+ * ONCE and can never be read back.
+ *
+ * Exactly one of the two fields carries it, decided by
+ * {@link ApplicationCredentialType}: `secret` for a `confidential`/`service`
+ * client, `token` for a `machine` API key, and NEITHER for a `public` client
+ * (`secret` is `null`). They are separate fields rather than one, so a surface
+ * that renders "the secret" cannot silently render an API key's bearer token
+ * under the wrong label, or a `null` where a token should be.
+ */
+export interface ApplicationCredentialWithSecret {
+    credential: ApplicationCredential;
+    /** The OAuth client secret. `null` for `public` and `machine` credentials. */
+    secret: string | null;
+    /** The full `oxy_sk_…` bearer token. Present ONLY for a `machine` credential. */
+    token?: string;
+}
+/**
+ * Result of rotating an application credential. Extends the create result with
+ * audit fields: the new credential material is returned ONCE, plus `rotatedFrom`
+ * (the previous credential's `credentialId`) and `graceExpiresAt`.
+ */
+export interface RotateApplicationCredentialResult extends ApplicationCredentialWithSecret {
+    /** The previous credential's `credentialId` that this rotation supersedes. */
+    rotatedFrom: string;
+    /**
+     * ISO timestamp at which the rotated-from credential stops being honoured, or
+     * `null` when no grace window was configured and it was revoked outright.
+     *
+     * Nullable because a `machine` credential's grace is OPT-IN (issue #972 §2.3):
+     * rotating an API key without asking for a window kills the old token
+     * immediately, and there is then no deadline to report. The OAuth/service
+     * types always carry their fixed seven-day deadline.
+     */
+    graceExpiresAt: string | null;
+}
+/** Time window for application usage statistics. */
+export type ApplicationUsagePeriod = '24h' | '7d' | '30d' | '90d';
+/** Aggregate totals for an application over the requested period. */
+export interface ApplicationUsageSummary {
+    totalRequests: number;
+    totalTokens: number;
+    totalCredits: number;
+    avgResponseTime: number;
+    successfulRequests: number;
+    errorRequests: number;
+}
+/** Per-day usage bucket. `_id` is the day key (e.g. `YYYY-MM-DD`). */
+export interface ApplicationUsageByDay {
+    _id: string;
+    requests: number;
+    tokens: number;
+    credits: number;
+}
+/** Per-endpoint usage bucket. `_id` is the endpoint identifier. */
+export interface ApplicationUsageByEndpoint {
+    _id: string;
+    requests: number;
+    tokens: number;
+}
+/** Usage statistics for an application over a period. */
+export interface ApplicationUsageStats {
+    summary: ApplicationUsageSummary;
+    byDay: ApplicationUsageByDay[];
+    byEndpoint: ApplicationUsageByEndpoint[];
+}
+/**
+ * Sanitized, PUBLIC application identity returned by the API when resolving a
+ * cross-app/OAuth client to a registered application.
+ *
+ * This shape carries NO sensitive or membership fields — it is safe to display
+ * unauthenticated in consent/authorize screens and device-flow approval UIs. The
+ * API resolves a `client_id` (OAuth credential public key) to the owning
+ * application and projects only the fields below. `id` is the application's
+ * `_id` as a string.
+ */
+export interface PublicApplication {
+    /** The application's Mongo `_id` as a string. */
+    id: string;
+    /** Human-readable application name shown to the user. */
+    name: string;
+    /** Optional short description of what the application does. */
+    description?: string;
+    /** Optional icon URL for the application. */
+    icon?: string;
+    /** Optional public website/homepage URL for the application. */
+    websiteUrl?: string;
+    /** Optional public privacy-policy URL, rendered as a legal link on the consent screen. */
+    privacyPolicyUrl?: string;
+    /** Optional public terms-of-service URL, rendered as a legal link on the consent screen. */
+    termsUrl?: string;
+    /** Application classification (set by Oxy platform staff). */
+    type: ApplicationType;
+    /** Whether the application is an officially endorsed Oxy application. */
+    isOfficial: boolean;
+    /** Whether the application is an internal Oxy ecosystem application. */
+    isInternal: boolean;
+    /** OAuth scopes the application is configured to request. */
+    scopes: string[];
+    /** Optional display name of the developer/owner organisation. */
+    developerName?: string;
+}
+/**
+ * A connected (OAuth-authorized) application from the current user's point of
+ * view: an application the user has granted access to via the consent flow.
+ *
+ * Returned by `GET /auth/grants` and rendered in the user-facing "Connected
+ * apps" management surface. Keyed by `applicationId` (the application's Mongo
+ * `_id`) rather than a credential/client id, so the grant — and a subsequent
+ * `apps.connected.revoke` — survive credential
+ * rotation. This is a display shape: it carries the application's name/logo and
+ * the granted scopes, never any membership or credential material.
+ */
+export interface ConnectedApp {
+    /** The connected application's Mongo `_id`. Use this to revoke the grant. */
+    applicationId: string;
+    /** Human-readable application name shown to the user. */
+    name: string;
+    /** Optional logo URL for the application. */
+    logoUrl?: string;
+    /** OAuth scopes the user has granted to the application. */
+    scopes: string[];
+    /** ISO timestamp of when the user first authorized the application. */
+    firstGrantedAt: string;
+    /** ISO timestamp of when the grant was last exercised. */
+    lastUsedAt: string;
+}
+/** An external MCP client authorized for one exact app resource and account. */
+export interface ConnectedMcpClient {
+    id: string;
+    appSlug: string;
+    resource: string;
+    scopes: string[];
+    clientId: string;
+    clientName: string;
+    createdAt: string;
+    lastUsedAt: string;
+}
+/** `oxy.apps.credentials` — an application's OAuth client credentials. */
+export declare class AppCredentialsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * List an application's OAuth credentials. The response NEVER includes
+     * secrets.
+     * @param applicationId - The application's `_id`.
+     */
+    list(applicationId: string): Promise<ApplicationCredential[]>;
+    /**
+     * Create an application credential. The plaintext `secret` is returned
+     * exactly ONCE; the server stores only a hash and will never return it again.
+     * @param applicationId - The application's `_id`.
+     * @param data - Credential configuration.
+     */
+    create(applicationId: string, data: CreateApplicationCredentialInput): Promise<ApplicationCredentialWithSecret>;
+    /**
+     * Rotate an application credential's secret. The new plaintext `secret` is
+     * returned exactly ONCE, along with audit fields: `rotatedFrom` (the previous
+     * credentialId) and `graceExpiresAt` (the end of the window during which the
+     * old credential is still honoured).
+     * @param applicationId - The application's `_id`.
+     * @param credentialId - The credential's `_id`.
+     * @param options - `graceSeconds` keeps a superseded `machine` token working
+     *   for that long. Omitted, the previous token dies the moment the
+     *   replacement is minted.
+     */
+    rotate(applicationId: string, credentialId: string, options?: RotateApplicationCredentialInput): Promise<RotateApplicationCredentialResult>;
+    /**
+     * Revoke an application credential (`status='revoked'`). Revoked credentials
+     * can no longer authenticate.
+     * @param applicationId - The application's `_id`.
+     * @param credentialId - The credential's `_id`.
+     */
+    revoke(applicationId: string, credentialId: string): Promise<AccountSuccessResult>;
+}
+/** `oxy.apps.connected` — third-party apps (and MCP clients) this user authorized. */
+export declare class ConnectedAppsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * The applications this user granted access to through the consent flow,
+     * with the granted scopes and when the grant was first made and last used.
+     * `GET /auth/grants`, briefly cached; `revoke` busts it.
+     */
+    list(): Promise<ConnectedApp[]>;
+    /**
+     * Revoke this user's grant for a connected application. After this the
+     * application can no longer act on the user's behalf until re-authorized.
+     * @param applicationId - The connected application's `_id` (a
+     *   `ConnectedApp.applicationId`, NOT a credential/client id).
+     */
+    revoke(applicationId: string): Promise<void>;
+    /** Resource-bound external MCP connections for the active Oxy account. */
+    mcpClients(): Promise<ConnectedMcpClient[]>;
+    /** Revoke one external MCP connection and every token in its family. */
+    revokeMcpClient(grantId: string): Promise<void>;
+}
+export declare class AppsApi {
+    private readonly ctx;
+    /** An application's OAuth client credentials. */
+    readonly credentials: AppCredentialsApi;
+    /** Third-party apps (and MCP clients) this user authorized. */
+    readonly connected: ConnectedAppsApi;
+    constructor(ctx: OxyContext);
+    /**
+     * The applications an account owns. `GET /applications?ownerAccountId=<id>`.
+     * @param accountId - The owning account's `_id`.
+     */
+    list(accountId: string): Promise<Application[]>;
+    /**
+     * Fetch a single application by id.
+     * @param applicationId - The application's `_id`.
+     */
+    get(applicationId: string): Promise<Application>;
+    /**
+     * Create an application owned by an account.
+     * @param data - Application configuration. `ownerAccountId` defaults to the
+     *   caller's personal account when omitted. Staff-only fields are ignored.
+     */
+    create(data: CreateApplicationInput): Promise<Application>;
+    /**
+     * Update an application's mutable fields.
+     * @param applicationId - The application's `_id`.
+     * @param data - Subset of updatable fields. Staff-only fields are ignored.
+     */
+    update(applicationId: string, data: UpdateApplicationInput): Promise<Application>;
+    /**
+     * Soft-delete an application.
+     * @param applicationId - The application's `_id`.
+     */
+    delete(applicationId: string): Promise<AccountSuccessResult>;
+    /**
+     * Usage statistics for an application.
+     * @param applicationId - The application's `_id`.
+     * @param period - Time window (defaults to the server default).
+     */
+    usage(applicationId: string, period?: ApplicationUsagePeriod): Promise<ApplicationUsageStats>;
+    /**
+     * Resolve an OAuth `client_id` (an active credential's public key) to the
+     * owning application's PUBLIC identity. No authentication required — only
+     * sanitized, display-safe metadata; use it to render the requesting app in
+     * consent, authorize, and device-flow approval screens before any session
+     * exists.
+     */
+    getPublic(clientId: string): Promise<PublicApplication>;
+    /**
+     * Bust every cached application list — the unscoped entry and every
+     * owner-scoped `GET:/applications?ownerAccountId=<id>` variant — plus any
+     * extra keys, in one pass. The `?` prefix never matches the
+     * `GET:/applications/<id>…` detail keys.
+     */
+    private invalidateLists;
+}

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

@@ -0,0 +1,174 @@
+import type { OxyContext } from '../client/context';
+import type { AccountStorageUsageResponse, Asset, AssetDeleteSummary, AssetLink, AssetMetadata, AssetUploadInput, BatchFileAccessResponse, FileVisibility } from '../models/interfaces';
+/**
+ * How long a resolved asset URL may stay in the SDK's GET cache, in ms: never
+ * longer than the media token's lifetime, and discounted below it.
+ */
+export declare function assetUrlCacheTTL(expiresIn?: number): number;
+/** An asset as `GET /assets/:id` and `GET /assets` return it. */
+export type AssetRecord = Omit<Asset, 'visibility'> & {
+    visibility?: FileVisibility;
+};
+/** The asset `POST /assets/upload` returns. */
+export type UploadedAsset = Pick<Asset, 'id' | 'sha256' | 'size' | 'mime' | 'ext' | 'visibility' | 'links' | 'variants'> & {
+    originalName?: string;
+    metadata?: AssetMetadata;
+};
+/** An asset's link state after a link or unlink. */
+export interface AssetLinkState {
+    id: string;
+    usageCount: number;
+    links: AssetLink[];
+    status: Asset['status'];
+}
+export interface AssetUploadOptions {
+    /** Server default: `private`. */
+    visibility?: FileVisibility;
+    metadata?: AssetMetadata;
+    /** Called with `100` once the upload completes. */
+    onProgress?: (progress: number) => void;
+}
+export interface AssetLinkTarget {
+    app: string;
+    entityType: string;
+    entityId: string;
+}
+export interface AssetDeleteResult {
+    summary: AssetDeleteSummary;
+    message: string;
+    force?: boolean;
+}
+export declare class AssetsApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /**
+     * Upload a file. Accepts a web `File`/`Blob` or a React Native
+     * `{ uri, type?, name?, size? }` descriptor.
+     *
+     * On React Native the descriptor goes into the multipart body as-is (RN's
+     * FormData reads the file from disk). On the web a plain `{ uri }` cannot be
+     * read by FormData (it would upload `[object Object]` — a 0-byte asset), so
+     * the uri is materialised into a Blob first; an empty result throws.
+     */
+    upload(file: AssetUploadInput, options?: AssetUploadOptions): Promise<{
+        file: UploadedAsset;
+    }>;
+    /**
+     * Upload a public avatar and link it to `userId`'s profile. Does not change
+     * the profile's `avatar` field — set it with `users.updateMe`.
+     */
+    uploadAvatar(file: AssetUploadInput, userId: string, app?: string): Promise<{
+        file: UploadedAsset;
+    }>;
+    /** Link an asset to an entity (what keeps it alive). */
+    link(fileId: string, target: AssetLinkTarget, options?: {
+        visibility?: FileVisibility;
+        webhookUrl?: string;
+    }): Promise<{
+        assetId: string;
+        file: AssetLinkState;
+    }>;
+    /** Remove an asset's link to an entity. */
+    unlink(fileId: string, target: AssetLinkTarget): Promise<{
+        file: AssetLinkState;
+    }>;
+    /** An asset's record: size, mime, visibility, links, variants. */
+    get(fileId: string): Promise<{
+        assetId: string;
+        file: AssetRecord;
+    }>;
+    /** The signed-in user's files, newest first. */
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        files: AssetRecord[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /** The account's storage usage, aggregated from its assets. */
+    usage(): Promise<AccountStorageUsageResponse>;
+    /**
+     * A URL for `fileId` valid for the CURRENT caller, whatever its visibility
+     * (`GET /assets/:id/url`): the CDN form for a public asset, an API-origin
+     * stream URL with a scoped media token for a private one the caller may
+     * read. Returned exactly as the API produced it.
+     *
+     * Throws {@link AssetUrlResolutionError} when the API returns no URL or the
+     * request fails (401/403/404 included) — deliberately never falling back to
+     * {@link publicUrl}, which would hand back a known-404 for a private asset and
+     * hide the real failure.
+     *
+     * Cached per identity for well under the media token's lifetime.
+     */
+    url(fileId: string, variant?: string, expiresIn?: number): Promise<string>;
+    /**
+     * A synchronous `<img src>` URL for an asset KNOWN to be **public** — a pure
+     * string builder with no knowledge of visibility: `${cloudURL}/<id>[?variant]`.
+     * A private or unlisted asset 404s there; use {@link url}.
+     *
+     * It never embeds the caller's bearer token (the string lands in DOM
+     * attributes, network panels, caches and logs). With `expiresIn` it builds
+     * the API-origin stream form, still credential-less: there is no synchronous
+     * private-asset path.
+     */
+    publicUrl(fileId: string, variant?: string, expiresIn?: number): string;
+    /**
+     * {@link url} for many assets — each with its OWN variant — in one round
+     * trip. Ids the caller cannot read (or that do not exist) are OMITTED from
+     * the map: no CDN fallback, so a grid never renders a known-404. Keyed by
+     * `fileId`.
+     */
+    urls(requests: Array<{
+        fileId: string;
+        variant?: string;
+    }>, options?: {
+        expiresIn?: number;
+        context?: string;
+    }): Promise<Record<string, string>>;
+    /**
+     * The raw per-file access envelope behind {@link urls}
+     * (`POST /assets/batch-access`): `allowed`, `url`, `visibility`, `mime` or
+     * `error` per file. Blank ids are dropped and exact `(fileId, variant)`
+     * duplicates collapsed; an empty list makes no call. The server caps a batch
+     * at 100 entries.
+     */
+    access(requests: Array<{
+        fileId: string;
+        variant?: string;
+    }>, options?: {
+        expiresIn?: number;
+        context?: string;
+    }): Promise<BatchFileAccessResponse>;
+    /** An asset's content as text. */
+    text(fileId: string, variant?: string): Promise<string>;
+    /** An asset's content as a Blob. */
+    blob(fileId: string, variant?: string): Promise<Blob>;
+    /**
+     * Delete an asset. With active links the server refuses and answers the
+     * summary of what would break, unless `force`.
+     */
+    delete(fileId: string, options?: {
+        force?: boolean;
+    }): Promise<AssetDeleteResult>;
+    /** Restore an asset from the trash. */
+    restore(fileId: string): Promise<{
+        file: {
+            id: string;
+            status: Asset['status'];
+            usageCount: number;
+        };
+    }>;
+    /** Change an asset's visibility. */
+    setVisibility(fileId: string, visibility: FileVisibility): Promise<{
+        file: {
+            id: string;
+            visibility: FileVisibility;
+            updatedAt: string;
+        };
+    }>;
+    private resolveUrl;
+    private fetchContent;
+    /** Drop the cached record and every cached URL variant of an asset, in one pass. */
+    private evict;
+}