@oxyhq/core 2.4.1 → 3.0.0

package/dist/types/OxyServices.d.ts

@@ -82,7 +82,7 @@ import { composeOxyServices } from './mixins';
  * - **Payment**: Payment processing
  * - **Karma**: Karma system
  * - **Assets**: File upload and asset management
- * - **Developer**: Developer API management
+ * - **Applications**: Application, membership, and credential management
  * - **Location**: Location-based features
  * - **Analytics**: Analytics tracking
  * - **Devices**: Device management

package/dist/types/index.d.ts

@@ -33,6 +33,7 @@ export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServic
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
+export type { Application, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';

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

@@ -0,0 +1,317 @@
+/**
+ * Applications Methods Mixin
+ *
+ * Provides methods for managing Oxy applications, their members, and their
+ * credentials via the `/applications` API. An application is a multi-user
+ * entity: membership (with a role) grants permissions; credentials
+ * (public/confidential/service) carry OAuth client identifiers and the
+ * service-token API key material.
+ *
+ * Reference applications by their Mongo `_id` (`applicationId`) and credentials
+ * by their `credentialId`. Never by name.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * 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';
+/** Role a member holds within an application. */
+export type ApplicationRole = 'owner' | 'admin' | 'developer' | 'viewer' | 'billing';
+/** Membership lifecycle status. */
+export type ApplicationMemberStatus = 'active' | 'invited' | 'removed';
+/** Credential kind. `service` credentials mint service tokens. */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service';
+/** Deployment environment a credential is scoped to. */
+export type ApplicationEnvironment = 'development' | 'staging' | 'production';
+/** Credential lifecycle status. */
+export type ApplicationCredentialStatus = 'active' | 'deprecated' | 'revoked';
+/**
+ * Client-facing Application shape returned by the `/applications` API.
+ * Mirrors the server `Application` model with `_id` as a string and dates
+ * serialized to ISO strings.
+ */
+export interface Application {
+    _id: string;
+    name: string;
+    description?: string;
+    websiteUrl?: string;
+    icon?: string;
+    type: ApplicationType;
+    status: ApplicationStatus;
+    isOfficial: boolean;
+    isInternal: boolean;
+    capabilities: string[];
+    redirectUris: string[];
+    scopes: string[];
+    webhookUrl?: string;
+    devWebhookUrl?: string;
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * The calling user's own membership in this application, embedded by the API
+     * on list (`GET /applications`) and detail (`GET /applications/:appId`)
+     * responses. Use `callerMembership.permissions` to gate UI affordances.
+     */
+    callerMembership?: ApplicationMember;
+}
+/**
+ * Client-facing ApplicationMember shape. `permissions` is derived from `role`
+ * on the server at write time.
+ */
+export interface ApplicationMember {
+    _id: string;
+    applicationId: string;
+    userId: string;
+    role: ApplicationRole;
+    permissions: string[];
+    invitedByUserId?: string;
+    joinedAt?: string;
+    status: ApplicationMemberStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Client-facing ApplicationCredential shape. 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;
+    type: ApplicationCredentialType;
+    environment: ApplicationEnvironment;
+    scopes: string[];
+    status: ApplicationCredentialStatus;
+    lastUsedAt?: string;
+    expiresAt?: string;
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input accepted by `createApplication`. Staff-only fields are not settable here. */
+export interface CreateApplicationInput {
+    name: string;
+    description?: string;
+    websiteUrl?: string;
+    icon?: string;
+    redirectUris?: string[];
+    scopes?: string[];
+}
+/** Input accepted by `updateApplication`. Staff-only fields are not settable here. */
+export interface UpdateApplicationInput {
+    name?: string;
+    description?: string;
+    websiteUrl?: string;
+    icon?: string;
+    redirectUris?: string[];
+    scopes?: string[];
+    webhookUrl?: string;
+    devWebhookUrl?: string;
+    status?: ApplicationStatus;
+}
+/** Input accepted by `inviteApplicationMember`. The owner role cannot be invited. */
+export interface InviteApplicationMemberInput {
+    userId: string;
+    role: Exclude<ApplicationRole, 'owner'>;
+}
+/** Input accepted by `updateApplicationMember`. */
+export interface UpdateApplicationMemberInput {
+    role: ApplicationRole;
+}
+/** Input accepted by `transferApplicationOwnership`. */
+export interface TransferApplicationOwnershipInput {
+    userId: string;
+}
+/** Input accepted by `createApplicationCredential`. */
+export interface CreateApplicationCredentialInput {
+    name: string;
+    type: ApplicationCredentialType;
+    environment: ApplicationEnvironment;
+    scopes?: string[];
+}
+/** Result of creating or rotating a credential — `secret` is returned ONCE. */
+export interface ApplicationCredentialWithSecret {
+    credential: ApplicationCredential;
+    secret: string;
+}
+/** 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[];
+}
+/** Result of a delete/remove/revoke/transfer operation. */
+export interface ApplicationSuccessResult {
+    success: boolean;
+}
+export declare function OxyServicesApplicationsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * List applications the current user is an active member of.
+         */
+        getApplications(): Promise<Application[]>;
+        /**
+         * Create a new application. The caller becomes its `owner`.
+         * @param data - Application configuration. Staff-only fields are ignored.
+         */
+        createApplication(data: CreateApplicationInput): Promise<Application>;
+        /**
+         * Fetch a single application by id.
+         * @param applicationId - The application's Mongo `_id`.
+         */
+        getApplication(applicationId: string): Promise<Application>;
+        /**
+         * Update an application's mutable fields.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param data - Subset of updatable fields. Staff-only fields are ignored.
+         */
+        updateApplication(applicationId: string, data: UpdateApplicationInput): Promise<Application>;
+        /**
+         * Soft-delete an application (owner only).
+         * @param applicationId - The application's Mongo `_id`.
+         */
+        deleteApplication(applicationId: string): Promise<ApplicationSuccessResult>;
+        /**
+         * List members of an application.
+         * @param applicationId - The application's Mongo `_id`.
+         */
+        getApplicationMembers(applicationId: string): Promise<ApplicationMember[]>;
+        /**
+         * Add a member to an application.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param data - Target user id and role (never `owner`).
+         */
+        inviteApplicationMember(applicationId: string, data: InviteApplicationMemberInput): Promise<ApplicationMember>;
+        /**
+         * Change a member's role.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param memberId - The member's Mongo `_id`.
+         * @param data - New role.
+         */
+        updateApplicationMember(applicationId: string, memberId: string, data: UpdateApplicationMemberInput): Promise<ApplicationMember>;
+        /**
+         * Remove a member from an application.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param memberId - The member's Mongo `_id`.
+         */
+        removeApplicationMember(applicationId: string, memberId: string): Promise<ApplicationSuccessResult>;
+        /**
+         * Transfer ownership of an application to another member (owner only).
+         * Demotes the current owner to `admin` and promotes the target to `owner`.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param data - Target user id.
+         */
+        transferApplicationOwnership(applicationId: string, data: TransferApplicationOwnershipInput): Promise<ApplicationSuccessResult>;
+        /**
+         * List an application's credentials. The response NEVER includes secrets.
+         * @param applicationId - The application's Mongo `_id`.
+         */
+        getApplicationCredentials(applicationId: string): Promise<ApplicationCredential[]>;
+        /**
+         * Create a 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 Mongo `_id`.
+         * @param data - Credential configuration.
+         */
+        createApplicationCredential(applicationId: string, data: CreateApplicationCredentialInput): Promise<ApplicationCredentialWithSecret>;
+        /**
+         * Rotate a credential's secret. The new plaintext `secret` is returned
+         * exactly ONCE.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param credentialId - The credential's Mongo `_id`.
+         */
+        rotateApplicationCredential(applicationId: string, credentialId: string): Promise<ApplicationCredentialWithSecret>;
+        /**
+         * Revoke a credential (`status='revoked'`). Revoked credentials can no
+         * longer authenticate.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param credentialId - The credential's Mongo `_id`.
+         */
+        revokeApplicationCredential(applicationId: string, credentialId: string): Promise<ApplicationSuccessResult>;
+        /**
+         * Fetch usage statistics for an application.
+         * @param applicationId - The application's Mongo `_id`.
+         * @param period - Time window (defaults to the server default).
+         */
+        getApplicationUsage(applicationId: string, period?: ApplicationUsagePeriod): Promise<ApplicationUsageStats>;
+        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;
+        getSessionBaseUrl(): string;
+        getClient(): import("../HttpService").HttpService;
+        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, refreshToken?: 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;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | 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.auth.d.ts

@@ -127,8 +127,8 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * legitimate multi-tenant hosts that need to switch credentials cannot leak
          * one tenant's token to another tenant on the same instance.
          *
-         * @param apiKey - DeveloperApp API key (oxy_dk_*)
-         * @param apiSecret - DeveloperApp API secret
+         * @param apiKey - Application credential public key (oxy_dk_*)
+         * @param apiSecret - Application credential secret
          */
         configureServiceAuth(apiKey: string, apiSecret: string): void;
         /**
@@ -147,8 +147,8 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * This prevents an attacker who learned a peer's apiKey from extracting
          * their service token by polling with a wrong secret.
          *
-         * @param apiKey - DeveloperApp API key (optional if configureServiceAuth was called)
-         * @param apiSecret - DeveloperApp API secret (optional if configureServiceAuth was called)
+         * @param apiKey - Application credential public key (optional if configureServiceAuth was called)
+         * @param apiSecret - Application credential secret (optional if configureServiceAuth was called)
          */
         getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
         /**

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

@@ -27,7 +27,7 @@ export interface ServiceActingAsVerification {
 /**
  * Service app metadata attached to requests authenticated with service tokens.
  * `scopes` reflects the scopes granted to the app at signup time (from the
- * `DeveloperApp.scopes` field); route-level checks can require additional
+ * `Application.scopes` field); route-level checks can require additional
  * scope-narrowing via `requireScope()`.
  */
 export interface ServiceApp {

package/dist/types/mixins/index.d.ts

@@ -16,7 +16,7 @@ import { OxyServicesLanguageMixin } from './OxyServices.language';
 import { OxyServicesPaymentMixin } from './OxyServices.payment';
 import { OxyServicesKarmaMixin } from './OxyServices.karma';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
-import { OxyServicesDeveloperMixin } from './OxyServices.developer';
+import { OxyServicesApplicationsMixin } from './OxyServices.applications';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
 import { OxyServicesDevicesMixin } from './OxyServices.devices';
@@ -36,7 +36,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "2.4.1",
+  "version": "3.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/OxyServices.ts

@@ -85,7 +85,7 @@ import { composeOxyServices } from './mixins';
  * - **Payment**: Payment processing
  * - **Karma**: Karma system
  * - **Assets**: File upload and asset management
- * - **Developer**: Developer API management
+ * - **Applications**: Application, membership, and credential management
  * - **Location**: Location-based features
  * - **Analytics**: Analytics tracking
  * - **Devices**: Device management

package/src/index.ts

@@ -62,6 +62,35 @@ export type {
 } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 
+// ---------------------------------------------------------------------------
+// Applications (multi-user apps: membership, roles, credentials)
+// ---------------------------------------------------------------------------
+export type {
+    Application,
+    ApplicationMember,
+    ApplicationCredential,
+    ApplicationRole,
+    ApplicationType,
+    ApplicationStatus,
+    ApplicationMemberStatus,
+    ApplicationCredentialType,
+    ApplicationCredentialStatus,
+    ApplicationEnvironment,
+    CreateApplicationInput,
+    UpdateApplicationInput,
+    InviteApplicationMemberInput,
+    UpdateApplicationMemberInput,
+    TransferApplicationOwnershipInput,
+    CreateApplicationCredentialInput,
+    ApplicationCredentialWithSecret,
+    ApplicationUsagePeriod,
+    ApplicationUsageSummary,
+    ApplicationUsageByDay,
+    ApplicationUsageByEndpoint,
+    ApplicationUsageStats,
+    ApplicationSuccessResult,
+} from './mixins/OxyServices.applications';
+
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------