@nexussdk/contracts 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,52 @@
+
+> @nexussdk/contracts@0.0.1 build /home/runner/work/NexusSDK/NexusSDK/packages/contracts
+> tsup
+
+CLI Building entry: src/auth.ts, src/flags.ts, src/index.ts, src/rfc7807.ts, src/tracker.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/runner/work/NexusSDK/NexusSDK/packages/contracts/tsup.config.ts
+CLI Target: es2022
+CLI Cleaning output folder
+ESM Build start
+CJS Build start
+Generated an empty chunk: "auth".
+Generated an empty chunk: "flags".
+Generated an empty chunk: "tracker".
+Generated an empty chunk: "auth".
+Generated an empty chunk: "flags".
+Generated an empty chunk: "tracker".
+CJS dist/auth.cjs        82.00 B
+CJS dist/flags.cjs       84.00 B
+CJS dist/index.cjs       199.00 B
+CJS dist/rfc7807.cjs     203.00 B
+CJS dist/tracker.cjs     88.00 B
+CJS dist/auth.cjs.map    69.00 B
+CJS dist/flags.cjs.map   70.00 B
+CJS dist/index.cjs.map   2.58 KB
+CJS dist/rfc7807.cjs.map 2.58 KB
+CJS dist/tracker.cjs.map 72.00 B
+CJS ⚡️ Build success in 111ms
+ESM dist/auth.mjs        68.00 B
+ESM dist/flags.mjs       70.00 B
+ESM dist/index.mjs       168.00 B
+ESM dist/rfc7807.mjs     172.00 B
+ESM dist/tracker.mjs     74.00 B
+ESM dist/auth.mjs.map    69.00 B
+ESM dist/flags.mjs.map   70.00 B
+ESM dist/index.mjs.map   2.57 KB
+ESM dist/rfc7807.mjs.map 2.58 KB
+ESM dist/tracker.mjs.map 72.00 B
+ESM ⚡️ Build success in 113ms
+DTS Build start
+DTS ⚡️ Build success in 1002ms
+DTS dist/index.d.mts   607.00 B
+DTS dist/rfc7807.d.mts 2.49 KB
+DTS dist/tracker.d.mts 6.48 KB
+DTS dist/flags.d.mts   7.17 KB
+DTS dist/auth.d.mts    6.21 KB
+DTS dist/index.d.ts    603.00 B
+DTS dist/rfc7807.d.ts  2.49 KB
+DTS dist/tracker.d.ts  6.48 KB
+DTS dist/flags.d.ts    7.17 KB
+DTS dist/auth.d.ts     6.21 KB

package/dist/auth.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=auth.cjs.map
+//# sourceMappingURL=auth.cjs.map

package/dist/auth.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"auth.cjs"}

package/dist/auth.d.mts

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Authentication, Organization, Project, and API Key contracts.
+ * Governs multi-tenant B2B2C security and quota boundaries.
+ * @module @nexus/contracts/auth
+ */
+/**
+ * Subscription plan tiers determining rate limits and feature entitlements.
+ * @example
+ * const tier: PlanTier = 'PRO';
+ */
+type PlanTier = 'FREE' | 'PRO' | 'ENTERPRISE';
+/**
+ * Operational status of a tenant account.
+ * @example
+ * const status: AccountStatus = 'ACTIVE';
+ */
+type AccountStatus = 'ACTIVE' | 'SUSPENDED' | 'CANCELLED';
+/**
+ * Deployment environments for project isolation.
+ * @example
+ * const env: Environment = 'production';
+ */
+type Environment = 'development' | 'staging' | 'production';
+/**
+ * Cryptographic API Key permission scope.
+ * - `PUBLIC`: Embedded in client browsers. Permitted only for flag evaluation,
+ *   SSE subscriptions, and error ingestion.
+ * - `SECRET`: Secure server-side only. Full administrative CRUD operations.
+ * @example
+ * const keyType: ApiKeyType = 'PUBLIC';
+ */
+type ApiKeyType = 'PUBLIC' | 'SECRET';
+/**
+ * Represents a developer or organization account (Tenant).
+ *
+ * @example
+ * const account: Account = {
+ *   id: 'uuid-v4',
+ *   name: 'Acme Corp',
+ *   email: 'admin@acme.com',
+ *   planTier: 'PRO',
+ *   status: 'ACTIVE',
+ *   createdAt: '2024-01-01T00:00:00Z',
+ *   updatedAt: '2024-06-01T00:00:00Z',
+ * };
+ */
+interface Account {
+    /** Unique UUID v4 identifier. */
+    id: string;
+    /** Organization or developer display name. */
+    name: string;
+    /** Primary contact and authentication email. */
+    email: string;
+    /** Current billing entitlement tier. */
+    planTier: PlanTier;
+    /** Current operational state. */
+    status: AccountStatus;
+    /** Arbitrary organizational metadata. */
+    metadata?: Record<string, unknown>;
+    /** Timestamp when account was created. */
+    createdAt: string;
+    /** Timestamp when account was last modified. */
+    updatedAt: string;
+}
+/**
+ * Represents an isolated application owned by an Account.
+ *
+ * @example
+ * const project: Project = {
+ *   id: 'uuid-v4',
+ *   accountId: 'account-uuid-v4',
+ *   name: 'My App',
+ *   slug: 'my-app',
+ *   createdAt: '2024-01-01T00:00:00Z',
+ *   updatedAt: '2024-06-01T00:00:00Z',
+ * };
+ */
+interface Project {
+    /** Unique UUID v4 identifier. */
+    id: string;
+    /** Owning Account UUID v4 identifier. */
+    accountId: string;
+    /** Human-readable project name. */
+    name: string;
+    /** URL-friendly unique slug under the parent account. */
+    slug: string;
+    /** Project description. */
+    description?: string;
+    /** Timestamp of project creation. */
+    createdAt: string;
+    /** Timestamp of last modification. */
+    updatedAt: string;
+}
+/**
+ * Public or Secret API Key metadata used by Go-Gin and NestJS guards.
+ *
+ * @example
+ * const apiKey: ApiKey = {
+ *   id: 'uuid-v4',
+ *   projectId: 'project-uuid-v4',
+ *   environment: 'production',
+ *   keyType: 'PUBLIC',
+ *   keyPrefix: 'pk_live_a1b2',
+ *   keyHash: 'sha256hexstring...',
+ *   allowedDomains: ['https://mybrand.com'],
+ *   rateLimitPerMin: 1000,
+ *   monthlyEventsLimit: 100000,
+ *   currentMonthUsage: 4250,
+ *   usageResetAt: '2024-07-01T00:00:00Z',
+ *   isActive: true,
+ *   createdAt: '2024-01-01T00:00:00Z',
+ * };
+ */
+interface ApiKey {
+    /** Unique UUID v4 identifier. */
+    id: string;
+    /** Parent Project identifier. */
+    projectId: string;
+    /** Target deployment environment. */
+    environment: Environment;
+    /** Key capability level. */
+    keyType: ApiKeyType;
+    /** Public preview prefix (e.g. "pk_live_abcd1234"). Raw secret is never persisted. */
+    keyPrefix: string;
+    /** SHA-256 hash string (64 chars) matching stored database records. */
+    keyHash: string;
+    /** Whitelisted Origin domains for browser CORS security (e.g. ["https://mybrand.com"]). */
+    allowedDomains: string[];
+    /** Maximum allowed HTTP requests per minute. */
+    rateLimitPerMin: number;
+    /** Hard cap for error and event ingestion per calendar month. */
+    monthlyEventsLimit: number;
+    /** Current count of events processed in the active billing window. */
+    currentMonthUsage: number;
+    /** Timestamp when the current billing usage cycle resets. */
+    usageResetAt: string;
+    /** Flag toggle allowing immediate key revocation. */
+    isActive: boolean;
+    /** Timestamp when the key was last used in any API request. */
+    lastUsedAt?: string;
+    /** Creation timestamp. */
+    createdAt: string;
+}
+/**
+ * Payload returned to the developer upon key generation.
+ * This is the ONLY time the raw token is made visible.
+ *
+ * @example
+ * const response: GeneratedApiKeyResponse = {
+ *   apiKey: { ... },
+ *   rawKey: 'pk_live_a1b2c3d4e5f6...',
+ * };
+ */
+interface GeneratedApiKeyResponse {
+    /** Public or Secret key metadata entity. */
+    apiKey: ApiKey;
+    /**
+     * Plaintext unhashed API key string (e.g., 'pk_live_a1b2c3...').
+     * Must be securely copied by developer; cannot be recovered after this response.
+     */
+    rawKey: string;
+}
+/**
+ * DTO for account registration requests.
+ *
+ * @example
+ * const dto: RegisterAccountDto = {
+ *   name: 'Acme Corp',
+ *   email: 'admin@acme.com',
+ *   password: 'S3cur3P@ssw0rd!',
+ * };
+ */
+interface RegisterAccountDto {
+    /** Organization display name. */
+    name: string;
+    /** Primary contact email. */
+    email: string;
+    /** Plaintext password (hashed server-side with bcrypt). */
+    password: string;
+}
+/**
+ * DTO for login requests.
+ *
+ * @example
+ * const dto: LoginDto = {
+ *   email: 'admin@acme.com',
+ *   password: 'S3cur3P@ssw0rd!',
+ * };
+ */
+interface LoginDto {
+    /** Registered email address. */
+    email: string;
+    /** Plaintext password to verify against stored bcrypt hash. */
+    password: string;
+}
+/**
+ * Session payload embedded in JWT and HttpOnly cookies.
+ *
+ * @example
+ * const session: SessionPayload = {
+ *   accountId: 'uuid-v4',
+ *   email: 'admin@acme.com',
+ *   planTier: 'PRO',
+ * };
+ */
+interface SessionPayload {
+    /** Authenticated account's UUID. */
+    accountId: string;
+    /** Authenticated account's email. */
+    email: string;
+    /** Plan tier for feature entitlement checks. */
+    planTier: PlanTier;
+}
+
+export type { Account, AccountStatus, ApiKey, ApiKeyType, Environment, GeneratedApiKeyResponse, LoginDto, PlanTier, Project, RegisterAccountDto, SessionPayload };

package/dist/auth.d.ts

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Authentication, Organization, Project, and API Key contracts.
+ * Governs multi-tenant B2B2C security and quota boundaries.
+ * @module @nexus/contracts/auth
+ */
+/**
+ * Subscription plan tiers determining rate limits and feature entitlements.
+ * @example
+ * const tier: PlanTier = 'PRO';
+ */
+type PlanTier = 'FREE' | 'PRO' | 'ENTERPRISE';
+/**
+ * Operational status of a tenant account.
+ * @example
+ * const status: AccountStatus = 'ACTIVE';
+ */
+type AccountStatus = 'ACTIVE' | 'SUSPENDED' | 'CANCELLED';
+/**
+ * Deployment environments for project isolation.
+ * @example
+ * const env: Environment = 'production';
+ */
+type Environment = 'development' | 'staging' | 'production';
+/**
+ * Cryptographic API Key permission scope.
+ * - `PUBLIC`: Embedded in client browsers. Permitted only for flag evaluation,
+ *   SSE subscriptions, and error ingestion.
+ * - `SECRET`: Secure server-side only. Full administrative CRUD operations.
+ * @example
+ * const keyType: ApiKeyType = 'PUBLIC';
+ */
+type ApiKeyType = 'PUBLIC' | 'SECRET';
+/**
+ * Represents a developer or organization account (Tenant).
+ *
+ * @example
+ * const account: Account = {
+ *   id: 'uuid-v4',
+ *   name: 'Acme Corp',
+ *   email: 'admin@acme.com',
+ *   planTier: 'PRO',
+ *   status: 'ACTIVE',
+ *   createdAt: '2024-01-01T00:00:00Z',
+ *   updatedAt: '2024-06-01T00:00:00Z',
+ * };
+ */
+interface Account {
+    /** Unique UUID v4 identifier. */
+    id: string;
+    /** Organization or developer display name. */
+    name: string;
+    /** Primary contact and authentication email. */
+    email: string;
+    /** Current billing entitlement tier. */
+    planTier: PlanTier;
+    /** Current operational state. */
+    status: AccountStatus;
+    /** Arbitrary organizational metadata. */
+    metadata?: Record<string, unknown>;
+    /** Timestamp when account was created. */
+    createdAt: string;
+    /** Timestamp when account was last modified. */
+    updatedAt: string;
+}
+/**
+ * Represents an isolated application owned by an Account.
+ *
+ * @example
+ * const project: Project = {
+ *   id: 'uuid-v4',
+ *   accountId: 'account-uuid-v4',
+ *   name: 'My App',
+ *   slug: 'my-app',
+ *   createdAt: '2024-01-01T00:00:00Z',
+ *   updatedAt: '2024-06-01T00:00:00Z',
+ * };
+ */
+interface Project {
+    /** Unique UUID v4 identifier. */
+    id: string;
+    /** Owning Account UUID v4 identifier. */
+    accountId: string;
+    /** Human-readable project name. */
+    name: string;
+    /** URL-friendly unique slug under the parent account. */
+    slug: string;
+    /** Project description. */
+    description?: string;
+    /** Timestamp of project creation. */
+    createdAt: string;
+    /** Timestamp of last modification. */
+    updatedAt: string;
+}
+/**
+ * Public or Secret API Key metadata used by Go-Gin and NestJS guards.
+ *
+ * @example
+ * const apiKey: ApiKey = {
+ *   id: 'uuid-v4',
+ *   projectId: 'project-uuid-v4',
+ *   environment: 'production',
+ *   keyType: 'PUBLIC',
+ *   keyPrefix: 'pk_live_a1b2',
+ *   keyHash: 'sha256hexstring...',
+ *   allowedDomains: ['https://mybrand.com'],
+ *   rateLimitPerMin: 1000,
+ *   monthlyEventsLimit: 100000,
+ *   currentMonthUsage: 4250,
+ *   usageResetAt: '2024-07-01T00:00:00Z',
+ *   isActive: true,
+ *   createdAt: '2024-01-01T00:00:00Z',
+ * };
+ */
+interface ApiKey {
+    /** Unique UUID v4 identifier. */
+    id: string;
+    /** Parent Project identifier. */
+    projectId: string;
+    /** Target deployment environment. */
+    environment: Environment;
+    /** Key capability level. */
+    keyType: ApiKeyType;
+    /** Public preview prefix (e.g. "pk_live_abcd1234"). Raw secret is never persisted. */
+    keyPrefix: string;
+    /** SHA-256 hash string (64 chars) matching stored database records. */
+    keyHash: string;
+    /** Whitelisted Origin domains for browser CORS security (e.g. ["https://mybrand.com"]). */
+    allowedDomains: string[];
+    /** Maximum allowed HTTP requests per minute. */
+    rateLimitPerMin: number;
+    /** Hard cap for error and event ingestion per calendar month. */
+    monthlyEventsLimit: number;
+    /** Current count of events processed in the active billing window. */
+    currentMonthUsage: number;
+    /** Timestamp when the current billing usage cycle resets. */
+    usageResetAt: string;
+    /** Flag toggle allowing immediate key revocation. */
+    isActive: boolean;
+    /** Timestamp when the key was last used in any API request. */
+    lastUsedAt?: string;
+    /** Creation timestamp. */
+    createdAt: string;
+}
+/**
+ * Payload returned to the developer upon key generation.
+ * This is the ONLY time the raw token is made visible.
+ *
+ * @example
+ * const response: GeneratedApiKeyResponse = {
+ *   apiKey: { ... },
+ *   rawKey: 'pk_live_a1b2c3d4e5f6...',
+ * };
+ */
+interface GeneratedApiKeyResponse {
+    /** Public or Secret key metadata entity. */
+    apiKey: ApiKey;
+    /**
+     * Plaintext unhashed API key string (e.g., 'pk_live_a1b2c3...').
+     * Must be securely copied by developer; cannot be recovered after this response.
+     */
+    rawKey: string;
+}
+/**
+ * DTO for account registration requests.
+ *
+ * @example
+ * const dto: RegisterAccountDto = {
+ *   name: 'Acme Corp',
+ *   email: 'admin@acme.com',
+ *   password: 'S3cur3P@ssw0rd!',
+ * };
+ */
+interface RegisterAccountDto {
+    /** Organization display name. */
+    name: string;
+    /** Primary contact email. */
+    email: string;
+    /** Plaintext password (hashed server-side with bcrypt). */
+    password: string;
+}
+/**
+ * DTO for login requests.
+ *
+ * @example
+ * const dto: LoginDto = {
+ *   email: 'admin@acme.com',
+ *   password: 'S3cur3P@ssw0rd!',
+ * };
+ */
+interface LoginDto {
+    /** Registered email address. */
+    email: string;
+    /** Plaintext password to verify against stored bcrypt hash. */
+    password: string;
+}
+/**
+ * Session payload embedded in JWT and HttpOnly cookies.
+ *
+ * @example
+ * const session: SessionPayload = {
+ *   accountId: 'uuid-v4',
+ *   email: 'admin@acme.com',
+ *   planTier: 'PRO',
+ * };
+ */
+interface SessionPayload {
+    /** Authenticated account's UUID. */
+    accountId: string;
+    /** Authenticated account's email. */
+    email: string;
+    /** Plan tier for feature entitlement checks. */
+    planTier: PlanTier;
+}
+
+export type { Account, AccountStatus, ApiKey, ApiKeyType, Environment, GeneratedApiKeyResponse, LoginDto, PlanTier, Project, RegisterAccountDto, SessionPayload };

package/dist/auth.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=auth.mjs.map
+//# sourceMappingURL=auth.mjs.map

package/dist/auth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"auth.mjs"}

package/dist/flags.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=flags.cjs.map
+//# sourceMappingURL=flags.cjs.map

package/dist/flags.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"flags.cjs"}