@technomoron/api-server-base 2.0.0-beta.21 → 2.0.0-beta.23

package/dist/cjs/common/types.cjs

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared type definitions used by both api-server-base and api-client-base.
+ * This file contains only `type`/`interface` declarations — no runtime code.
+ * Both packages reference these types via `import type`. Note that TypeScript
+ * does NOT inline `import type` references in emitted `.d.ts` files — the
+ * path aliases persist. Source files therefore keep inline type definitions
+ * to avoid broken references for consumers of the published packages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/common/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Shared type definitions used by both api-server-base and api-client-base.
+ * This file contains only `type`/`interface` declarations — no runtime code.
+ * Both packages reference these types via `import type`. Note that TypeScript
+ * does NOT inline `import type` references in emitted `.d.ts` files — the
+ * path aliases persist. Source files therefore keep inline type definitions
+ * to avoid broken references for consumers of the published packages.
+ */
+export type AuthIdentifier = string | number;
+export type SafeUser = Record<string, unknown>;
+export interface ApiResponseData<T = unknown> {
+    success: boolean;
+    code: number;
+    message: string;
+    data: T | null;
+    errors: Record<string, string>;
+}
+export interface AuthTokenData<User = SafeUser> {
+    accessToken?: string;
+    refreshToken?: string;
+    user?: User;
+}
+export interface WhoAmIResponseData<User = SafeUser, UserId extends AuthIdentifier = AuthIdentifier> {
+    user: User;
+    isImpersonating: boolean;
+    realUser?: User | null;
+    realUserId?: UserId | null;
+}
+export interface LogoutResponseData {
+    revoked: number;
+}
+export type TokenStatus = 'active' | 'expired' | 'revoked';
+export interface Token {
+    accessToken: string;
+    refreshToken: string;
+    userId: string;
+    expires?: Date;
+    issuedAt?: Date;
+    lastSeenAt?: Date;
+    status?: TokenStatus;
+    ruid?: string;
+    clientId?: string;
+    /**
+     * Optional session partition key. Token stores may use `domain` and `fingerprint`
+     * to replace previous sessions that match the same bucket.
+     */
+    domain?: string;
+    /**
+     * Optional device/session fingerprint used together with `domain` for session bucketing.
+     */
+    fingerprint?: string;
+    label?: string;
+    browser?: string;
+    device?: string;
+    ip?: string;
+    os?: string;
+    scope?: string[];
+    loginType?: string;
+    refreshTtlSeconds?: number;
+    sessionCookie?: boolean;
+}
+export interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+}
+export interface OAuthClient {
+    clientId: string;
+    clientSecret?: string;
+    hasSecret?: boolean;
+    firstParty?: boolean;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    redirectUris: string[];
+    scope?: string[];
+}
+export interface AuthCodeData {
+    code: string;
+    clientId: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'plain' | 'S256';
+    expiresAt: Date;
+    metadata?: Record<string, unknown>;
+    redirectUri?: string;
+    scope?: string[];
+    userId: AuthIdentifier;
+}
+export type AuthCode = AuthCodeData;
+export type AuthCodeRequest = Omit<AuthCodeData, 'code' | 'expiresAt'> & {
+    code?: string;
+    expiresInSeconds?: number;
+};
+export interface OAuthStartParams {
+    provider: string;
+    redirectUri?: string;
+    scope?: string | string[];
+    state?: string;
+    extras?: Record<string, unknown>;
+}
+export interface OAuthStartResult extends Record<string, unknown> {
+    url: string;
+    state?: string;
+    codeVerifier?: string;
+}
+export interface OAuthCallbackParams {
+    provider: string;
+    query: Record<string, string | string[]>;
+    body: Record<string, unknown>;
+}
+export interface OAuthCallbackResult<PublicUser> extends Record<string, unknown> {
+    user: PublicUser;
+    tokens?: {
+        accessToken: string;
+        refreshToken: string;
+    };
+}
+export type TusMetadata = Record<string, string>;
+export interface TusUploadRecord {
+    id: string;
+    length: number;
+    offset: number;
+    metadata: TusMetadata;
+    userId?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    completedAt?: Date;
+}
+export interface TusCreateUploadInput {
+    id?: string;
+    length: number;
+    metadata: TusMetadata;
+    userId?: string;
+}
+export interface TusAppendInput {
+    uploadId: string;
+    offset: number;
+    chunk: Buffer;
+}

package/dist/cjs/{api-module.cjs → server/src/api-module.cjs}

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiModule = void 0;
+/** Base class for feature modules mounted into {@link ApiServer}. */
 class ApiModule {
+    /** The server instance this module is mounted on. */
     get server() {
         if (this._server === undefined) {
             throw new Error('ApiModule.server is not set. Mount the module with ApiServer.api(...) before using it.');
@@ -15,12 +17,18 @@ class ApiModule {
         this.mountpath = '';
         this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';
     }
+    /** Optional pre-mount configuration validation hook. */
     checkConfig() {
         return true;
     }
+    /** Return all routes exposed by this module. */
     defineRoutes() {
         return [];
     }
+    /** Optional mount-time hook for modules that need direct server integration. */
+    onMount() {
+        return;
+    }
 }
 exports.ApiModule = ApiModule;
 ApiModule.defaultNamespace = '';

package/dist/{esm → cjs/server/src}/api-module.d.ts

@@ -4,7 +4,10 @@ export type ApiHandler<Data = unknown> = (apiReq: ApiRequest) => Promise<ApiHand
 export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
+    /** Real user identity — who the key belongs to. */
     uid: unknown;
+    /** Effective user identity — who the key acts as. When set, the request is treated as impersonation (isImpersonating() === true). */
+    euid?: unknown;
 }
 export type ApiRoute = {
     method: 'get' | 'post' | 'put' | 'patch' | 'delete';
@@ -14,17 +17,29 @@ export type ApiRoute = {
         type: ApiAuthType;
         req: ApiAuthClass;
     };
+    schema?: {
+        body?: Record<string, unknown>;
+        querystring?: Record<string, unknown>;
+        params?: Record<string, unknown>;
+    };
 };
+/** Base class for feature modules mounted into {@link ApiServer}. */
 export declare class ApiModule<T = unknown> {
     private _server?;
+    /** The server instance this module is mounted on. */
     get server(): T;
     set server(value: T);
+    /** Route namespace under `apiBasePath`. */
     namespace: string;
     mountpath: string;
     static defaultNamespace: string;
     constructor(opts?: {
         namespace?: string;
     });
+    /** Optional pre-mount configuration validation hook. */
     checkConfig(): boolean;
+    /** Return all routes exposed by this module. */
     defineRoutes(): ApiRoute[];
+    /** Optional mount-time hook for modules that need direct server integration. */
+    onMount(): void;
 }