@uploadista/server 0.0.3

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> @uploadista/server@0.0.2 build /Users/denislaboureyras/Documents/uploadista/dev/uploadista-workspace/uploadista-sdk/packages/servers/server
+> tsc -b
+

package/.turbo/turbo-check.log

@@ -0,0 +1,34 @@
+
+> @uploadista/server@ check /Users/denislaboureyras/Documents/uploadista/dev/uploadista/packages/uploadista/servers/server
+> biome check --write ./src
+
+src/cloudflare-config.ts:15:55 lint/suspicious/noExplicitAny ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ! Unexpected any. Specify a different type.
+  
+    13 │   STORAGE_ENCRYPTION_KEY: string;
+    14 │   STORAGE_ENCRYPTION_IV_LENGTH: string;
+  > 15 │   UPLOAD_EVENT_DURABLE_OBJECT: DurableObjectNamespace<any>;
+       │                                                       ^^^
+    16 │ };
+    17 │ 
+  
+  i any disables many type checking rules. Its use should be avoided.
+  
+
+src/cloudflare-config.ts:31:16 lint/suspicious/noExplicitAny ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ! Unexpected any. Specify a different type.
+  
+    29 │       storageIvLength?: string;
+    30 │     },
+  > 31 │   ) => Promise<any>;
+       │                ^^^
+    32 │ };
+    33 │ 
+  
+Checked 2 files in 36ms. No fixes applied.
+Found 2 warnings.
+  i any disables many type checking rules. Its use should be avoided.
+  
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 uploadista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,503 @@
+# @uploadista/server
+
+Core server utilities and authentication for Uploadista file upload and flow processing.
+
+This package provides framework-agnostic server components including authentication context management, caching utilities, and layer composition helpers. Use this with adapter packages (`@uploadista/adapters-hono`, `@uploadista/adapters-express`, `@uploadista/adapters-fastify`) to set up complete upload servers.
+
+## Features
+
+- **Authentication Context** - User identity and metadata management
+- **Auth Caching** - LRU cache for auth contexts with TTL support
+- **Effect Layers** - Dependency injection for upload and flow servers
+- **Error Handling** - Standardized error responses with HTTP status codes
+- **HTTP Utilities** - Route parsing and error mapping helpers
+- **TypeScript** - Full type safety with comprehensive JSDoc
+
+## Installation
+
+```bash
+npm install @uploadista/server @uploadista/core
+# or
+pnpm add @uploadista/server @uploadista/core
+```
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.0+ (optional but recommended)
+
+## Quick Start
+
+### 1. Set Up Authentication
+
+```typescript
+import { AuthContextServiceLive } from "@uploadista/server";
+import { Effect } from "effect";
+
+// Create auth context for a request
+const authContext = {
+  clientId: "user-123",
+  metadata: {
+    permissions: ["upload:create", "flow:execute"],
+    quota: { storage: 1000000000 }, // 1GB
+  },
+};
+
+// Provide auth context to your effects
+const effect = Effect.service(AuthContextService).pipe(
+  Effect.andThen((authService) => authService.getClientId()),
+);
+
+const result = await Effect.runPromise(
+  effect.pipe(Effect.provide(AuthContextServiceLive(authContext))),
+);
+console.log(result); // "user-123"
+```
+
+### 2. Get JWT Credentials
+
+```typescript
+import { getAuthCredentials } from "@uploadista/server";
+
+// Exchange credentials for JWT token
+const response = await getAuthCredentials({
+  uploadistaClientId: process.env.UPLOADISTA_CLIENT_ID,
+  uploadistaApiKey: process.env.UPLOADISTA_API_KEY,
+});
+
+if (response.isValid) {
+  console.log(`Token: ${response.data.token}`);
+  console.log(`Expires in: ${response.data.expiresIn}s`);
+} else {
+  console.error(`Auth failed: ${response.error}`);
+}
+```
+
+### 3. Create Upload Server Layer
+
+```typescript
+import { createUploadServerLayer } from "@uploadista/server";
+import { redisKvStore } from "@uploadista/kv-store-redis";
+import { s3DataStore } from "@uploadista/data-store-s3";
+import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+import { memoryEventBroadcaster } from "@uploadista/event-broadcaster-memory";
+
+const uploadServerLayer = createUploadServerLayer({
+  kvStore: redisKvStore,
+  eventEmitter: webSocketEventEmitter,
+  dataStore: s3DataStore,
+});
+
+// Use in your framework adapter...
+```
+
+### 4. Create Flow Server Layer
+
+```typescript
+import { createFlowServerLayer } from "@uploadista/server";
+
+const flowServerLayer = createFlowServerLayer({
+  kvStore: redisKvStore,
+  eventEmitter: webSocketEventEmitter,
+  flowProvider: createFlowsEffect,
+  uploadServer: uploadServerLayer,
+});
+
+// Use in your framework adapter...
+```
+
+## API Reference
+
+### Authentication
+
+#### `AuthContext`
+
+User identity and authorization metadata.
+
+```typescript
+type AuthContext = {
+  clientId: string;
+  metadata?: Record<string, unknown>;
+  permissions?: string[];
+};
+```
+
+**Properties**:
+- `clientId` - Unique user identifier
+- `metadata` - Custom authorization metadata (permissions, quotas, etc.)
+- `permissions` - Array of permission strings for authorization
+
+#### `AuthContextService`
+
+Effect service for accessing auth context throughout request processing.
+
+```typescript
+export class AuthContextService extends Context.Tag("AuthContextService")<
+  AuthContextService,
+  {
+    readonly getClientId: () => Effect.Effect<string | null>;
+    readonly getMetadata: () => Effect.Effect<Record<string, unknown>>;
+    readonly hasPermission: (permission: string) => Effect.Effect<boolean>;
+    readonly getAuthContext: () => Effect.Effect<AuthContext | null>;
+  }
+>() {}
+```
+
+**Methods**:
+- `getClientId()` - Get current client ID
+- `getMetadata()` - Get auth metadata object
+- `hasPermission(permission)` - Check if user has permission
+- `getAuthContext()` - Get full auth context
+
+#### `AuthContextServiceLive(authContext)`
+
+Factory for creating AuthContextService layer.
+
+```typescript
+import { AuthContextServiceLive } from "@uploadista/server";
+
+const authLayer = AuthContextServiceLive({
+  clientId: "user-123",
+  permissions: ["upload:create"],
+});
+```
+
+#### `getAuthCredentials(params)`
+
+Exchange client credentials for JWT token.
+
+```typescript
+import { getAuthCredentials } from "@uploadista/server";
+
+const response = await getAuthCredentials({
+  uploadistaClientId: "my-client",
+  uploadistaApiKey: "sk_...",
+  baseUrl: "https://api.uploadista.com", // optional
+});
+
+if (response.isValid) {
+  // response.data.token - JWT token
+  // response.data.expiresIn - Seconds until expiration
+} else {
+  // response.error - Error message
+}
+```
+
+### Caching
+
+#### `AuthCacheConfig`
+
+Configuration for auth context caching.
+
+```typescript
+type AuthCacheConfig = {
+  maxSize?: number;     // Default: 10000
+  ttl?: number;        // Default: 3600000 (1 hour)
+};
+```
+
+#### `AuthCacheService`
+
+Effect service for storing and retrieving cached auth contexts.
+
+```typescript
+export class AuthCacheService extends Context.Tag("AuthCacheService")<
+  AuthCacheService,
+  {
+    readonly set: (
+      jobId: string,
+      authContext: AuthContext,
+    ) => Effect.Effect<void>;
+    readonly get: (jobId: string) => Effect.Effect<AuthContext | null>;
+    readonly delete: (jobId: string) => Effect.Effect<void>;
+    readonly clear: () => Effect.Effect<void>;
+    readonly size: () => Effect.Effect<number>;
+  }
+>() {}
+```
+
+**Methods**:
+- `set(jobId, authContext)` - Cache auth for a job
+- `get(jobId)` - Retrieve cached auth
+- `delete(jobId)` - Remove specific cache entry
+- `clear()` - Clear all cached entries
+- `size()` - Get number of cached entries
+
+#### `AuthCacheServiceLive(config?)`
+
+Create in-memory auth cache layer.
+
+```typescript
+import { AuthCacheServiceLive } from "@uploadista/server";
+
+const cacheLayer = AuthCacheServiceLive({
+  maxSize: 5000,
+  ttl: 1800000, // 30 minutes
+});
+```
+
+### Layer Composition
+
+#### `UploadServerLayerConfig`
+
+Configuration for creating upload server layer.
+
+```typescript
+interface UploadServerLayerConfig {
+  kvStore: Layer.Layer<BaseKvStoreService>;
+  eventEmitter: Layer.Layer<BaseEventEmitterService>;
+  dataStore: Layer.Layer<UploadFileDataStores, never, UploadFileKVStore>;
+  bufferedDataStore?: Layer.Layer<UploadFileDataStore>;
+  generateId?: Layer.Layer<GenerateId>;
+}
+```
+
+#### `createUploadServerLayer(config)`
+
+Compose upload server with all dependencies.
+
+```typescript
+import { createUploadServerLayer } from "@uploadista/server";
+
+const uploadLayer = createUploadServerLayer({
+  kvStore: redisKvStore,
+  eventEmitter: webSocketEventEmitter,
+  dataStore: s3DataStore,
+});
+```
+
+#### `FlowServerLayerConfig`
+
+Configuration for creating flow server layer.
+
+```typescript
+interface FlowServerLayerConfig {
+  kvStore: Layer.Layer<BaseKvStoreService>;
+  eventEmitter: Layer.Layer<BaseEventEmitterService>;
+  flowProvider: Layer.Layer<FlowProvider>;
+  uploadServer: Layer.Layer<UploadServer>;
+}
+```
+
+#### `createFlowServerLayer(config)`
+
+Compose flow server with all dependencies.
+
+```typescript
+import { createFlowServerLayer } from "@uploadista/server";
+
+const flowLayer = createFlowServerLayer({
+  kvStore: redisKvStore,
+  eventEmitter: webSocketEventEmitter,
+  flowProvider: createFlowsEffect,
+  uploadServer: uploadLayer,
+});
+```
+
+### Error Handling
+
+#### `AdapterError`
+
+Base error class for adapter errors.
+
+```typescript
+class AdapterError extends Error {
+  constructor(
+    message: string,
+    statusCode?: number,
+    errorCode?: string,
+  ) {}
+}
+```
+
+**Properties**:
+- `statusCode` - HTTP status code (default: 500)
+- `errorCode` - Machine-readable error code
+
+#### `ValidationError`, `NotFoundError`, `BadRequestError`
+
+Pre-configured error classes:
+
+```typescript
+import {
+  ValidationError,
+  NotFoundError,
+  BadRequestError,
+} from "@uploadista/server";
+
+// Validation error (400)
+throw new ValidationError("Invalid upload ID format");
+
+// Not found (404)
+throw new NotFoundError("Upload");
+
+// Bad request (400)
+throw new BadRequestError("Invalid JSON body");
+```
+
+#### Error Response Factories
+
+```typescript
+import {
+  createErrorResponseBody,
+  createUploadistaErrorResponseBody,
+  createGenericErrorResponseBody,
+} from "@uploadista/server";
+
+// For adapter errors
+const errorResponse = createErrorResponseBody(
+  new ValidationError("Invalid data"),
+);
+// => { error: "Invalid data", code: "VALIDATION_ERROR", timestamp: "..." }
+
+// For core library errors
+const uploadistaErrorResponse = createUploadistaErrorResponseBody(error);
+
+// For unknown errors
+const genericErrorResponse = createGenericErrorResponseBody("Something went wrong");
+```
+
+### HTTP Utilities
+
+```typescript
+import {
+  parseUrlSegments,
+  getLastSegment,
+  hasBasePath,
+  getRouteSegments,
+  handleFlowError,
+  extractJobIdFromStatus,
+  extractJobAndNodeId,
+  extractFlowAndStorageId,
+} from "@uploadista/server";
+
+// Parse route
+const segments = parseUrlSegments("/uploadista/api/upload/abc");
+// => ["uploadista", "api", "upload", "abc"]
+
+// Check if request is for uploadista
+const isUploadistaRequest = hasBasePath("/uploadista/api/upload", "uploadista");
+// => true
+
+// Extract parameters from URL
+const jobId = extractJobIdFromStatus(["jobs", "job-123", "status"]);
+// => "job-123"
+
+// Handle errors consistently
+const errorInfo = handleFlowError({
+  code: "FILE_NOT_FOUND",
+  message: "File not found",
+});
+// => { status: 404, code: "FILE_NOT_FOUND", message: "File not found" }
+```
+
+## Framework Integration
+
+This package is used by framework adapters:
+
+- **[@uploadista/adapters-hono](../adapters-hono/)** - For Cloudflare Workers
+- **[@uploadista/adapters-express](../adapters-express/)** - For Node.js Express
+- **[@uploadista/adapters-fastify](../adapters-fastify/)** - For Node.js Fastify
+
+## Complete Server Example
+
+```typescript
+import { Effect, Layer } from "effect";
+import {
+  createUploadServerLayer,
+  createFlowServerLayer,
+  AuthContextServiceLive,
+} from "@uploadista/server";
+import { redisKvStore } from "@uploadista/kv-store-redis";
+import { s3DataStore } from "@uploadista/data-store-s3";
+import { webSocketEventEmitter } from "@uploadista/event-emitter-websocket";
+
+// Configure servers
+const uploadLayer = createUploadServerLayer({
+  kvStore: redisKvStore,
+  eventEmitter: webSocketEventEmitter,
+  dataStore: s3DataStore,
+});
+
+const flowLayer = createFlowServerLayer({
+  kvStore: redisKvStore,
+  eventEmitter: webSocketEventEmitter,
+  flowProvider: createFlowsEffect,
+  uploadServer: uploadLayer,
+});
+
+// Set up authentication for a request
+const authContext = {
+  clientId: "user-123",
+  permissions: ["upload:create", "flow:execute"],
+};
+
+// Compose all layers
+const appLayer = Layer.provide(flowLayer, uploadLayer).pipe(
+  Layer.provide(AuthContextServiceLive(authContext)),
+);
+
+// Run effects
+const myEffect = Effect.gen(function* () {
+  const uploadServer = yield* UploadServer;
+  const flowServer = yield* FlowServer;
+  // ... use uploadServer and flowServer
+});
+
+Effect.runPromise(myEffect.pipe(Effect.provide(appLayer)));
+```
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive types:
+
+```typescript
+import type {
+  AuthContext,
+  AuthResult,
+  AuthCacheConfig,
+  UploadServerLayerConfig,
+  FlowServerLayerConfig,
+} from "@uploadista/server";
+import type { UploadServer, FlowServer } from "@uploadista/core";
+```
+
+## Architecture Notes
+
+### Authentication Flow
+
+1. Client authenticates with credentials (ID + API key)
+2. Server validates and issues JWT token
+3. Token includes user identity and permissions
+4. Subsequent requests include token in Authorization header
+5. Auth context created from token claims
+6. Auth context passed through Effect layers to handlers
+7. Handlers check permissions before processing
+
+### Effect Layer Pattern
+
+- Use `Layer.provide()` to compose dependencies
+- Each layer provides one service (UploadServer, FlowServer, etc.)
+- Auth context automatically available via AuthContextService
+- Cache automatically handles auth context persistence across requests
+
+### Error Handling Strategy
+
+1. Catch domain errors in handlers
+2. Map to AdapterError with appropriate HTTP status
+3. Format using createErrorResponseBody
+4. Return JSON error response with timestamp
+5. Log errors for monitoring
+
+## Related Packages
+
+- **[@uploadista/core](../../core/)** - Core upload and flow engine
+- **[@uploadista/adapters-hono](../adapters-hono/)** - Hono adapter
+- **[@uploadista/adapters-express](../adapters-express/)** - Express adapter
+- **[@uploadista/adapters-fastify](../adapters-fastify/)** - Fastify adapter
+- **[@uploadista/kv-store-redis](../../kv-stores/redis/)** - Redis KV store
+- **[@uploadista/data-store-s3](../../data-stores/s3/)** - AWS S3 storage
+
+## License
+
+MIT

package/dist/auth/cache.d.ts

@@ -0,0 +1,87 @@
+import { Context, Effect, Layer } from "effect";
+import type { AuthContext } from "./types";
+/**
+ * Configuration options for the auth cache.
+ */
+export type AuthCacheConfig = {
+    /**
+     * Maximum number of entries in the cache.
+     * When exceeded, oldest entries are removed (LRU eviction).
+     * @default 10000
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live for cache entries in milliseconds.
+     * Entries older than this will be automatically evicted.
+     * @default 3600000 (1 hour)
+     */
+    ttl?: number;
+};
+declare const AuthCacheService_base: Context.TagClass<AuthCacheService, "AuthCacheService", {
+    /**
+     * Store an auth context for a job ID.
+     */
+    readonly set: (jobId: string, authContext: AuthContext) => Effect.Effect<void>;
+    /**
+     * Retrieve a cached auth context by job ID.
+     * Returns null if not found or expired.
+     */
+    readonly get: (jobId: string) => Effect.Effect<AuthContext | null>;
+    /**
+     * Delete a cached auth context by job ID.
+     */
+    readonly delete: (jobId: string) => Effect.Effect<void>;
+    /**
+     * Clear all cached auth contexts.
+     */
+    readonly clear: () => Effect.Effect<void>;
+    /**
+     * Get the current number of cached entries.
+     */
+    readonly size: () => Effect.Effect<number>;
+}>;
+/**
+ * Auth Cache Service
+ *
+ * Provides caching of authentication contexts for upload and flow jobs.
+ * This allows subsequent operations (chunk uploads, flow continuations)
+ * to reuse the auth context from the initial request without re-authenticating.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { AuthCacheService } from "@uploadista/server";
+ *
+ * const handler = Effect.gen(function* () {
+ *   const authCache = yield* AuthCacheService;
+ *   const authContext = { userId: "user-123" };
+ *
+ *   // Cache auth for upload
+ *   yield* authCache.set("upload-abc", authContext);
+ *
+ *   // Retrieve cached auth later
+ *   const cached = yield* authCache.get("upload-abc");
+ *   console.log(cached?.userId); // "user-123"
+ *
+ *   // Clear when done
+ *   yield* authCache.delete("upload-abc");
+ * });
+ * ```
+ */
+export declare class AuthCacheService extends AuthCacheService_base {
+}
+/**
+ * Creates an AuthCacheService Layer with in-memory storage.
+ *
+ * @param config - Optional configuration for cache behavior
+ * @returns Effect Layer providing AuthCacheService
+ */
+export declare const AuthCacheServiceLive: (config?: AuthCacheConfig) => Layer.Layer<AuthCacheService>;
+/**
+ * No-op implementation of AuthCacheService.
+ * Does not cache anything - all operations are no-ops.
+ * Used when caching is disabled or not needed.
+ */
+export declare const NoAuthCacheServiceLive: Layer.Layer<AuthCacheService>;
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/auth/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/auth/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;;IAyCE;;OAEG;kBACW,CACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,KACrB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IAExB;;;OAGG;kBACW,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;IAElE;;OAEG;qBACc,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IAEvD;;OAEG;oBACa,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IAEzC;;OAEG;mBACY,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;;AA1D9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAiB,SAAQ,qBAgCnC;CAAG;AAEN;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,SAAQ,eAAoB,KAC3B,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAyF9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAO7D,CAAC"}