@edgespark/server-types 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,90 @@
+# @edgespark/server
+
+Type definitions for EdgeSpark Server SDK.
+
+## Overview
+
+This is a **types-only** package. The actual implementation lives in `edge/workers/user-worker/src/sdk-server/` and is deployed with the user-worker.
+
+```
+sdk/server-types/src/index.ts     ← Types (this package)
+        ↓
+    workspace:*
+        ↓
+sdk-server/                 ← Implementation (imports types from here)
+        ↓
+    deployed
+        ↓
+user-worker                 ← Runtime (serves SDK to user code)
+```
+
+## Development Flow
+
+### Adding a New Feature
+
+1. **Add types** in `sdk/server-types/src/index.ts`
+   ```typescript
+   export interface QueueClient {
+     send(message: string): Promise<void>;
+   }
+
+   export interface Client<TSchema> {
+     // ... existing
+     queue: QueueClient;  // new
+   }
+   ```
+
+2. **Implement** in `edge/workers/user-worker/src/sdk-server/`
+   ```typescript
+   import type { QueueClient } from "@edgespark/server-types";
+   // ... implementation
+   ```
+
+3. **Deploy user-worker** (implementation goes live)
+   ```bash
+   cd edge/workers/user-worker
+   wrangler deploy
+   ```
+
+4. **Publish types** to npm
+   ```bash
+   cd sdk/server
+   pnpm version minor   # 0.0.1 → 0.1.0
+   pnpm publish
+   ```
+
+### Types-Only Changes (JSDoc, comments)
+
+```bash
+cd sdk/server
+# Edit src/index.ts
+pnpm version patch   # 0.0.1 → 0.0.2
+pnpm publish
+```
+
+No deployment needed.
+
+## Rules
+
+| Rule | Why |
+|------|-----|
+| Deploy impl BEFORE publishing types | New types + old impl = runtime errors |
+| Types can publish WITHOUT deploy | JSDoc/comment changes are safe |
+| Use `workspace:*` locally | Instant feedback during dev |
+| Bump version on every publish | npm requires unique versions |
+
+## Local Development
+
+The `user-worker` package uses `"@edgespark/server-types": "workspace:*"` which means:
+- Changes to `sdk/server-types/src/index.ts` are immediately available
+- Run `pnpm build` in `sdk/server-types/` to update `dist/`
+- No need to publish during development
+
+## Publishing
+
+```bash
+cd sdk/server
+pnpm build              # Compile TypeScript
+pnpm version <patch|minor|major>
+pnpm publish --access public
+```

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @edgespark/server-types - Type definitions for EdgeSpark server SDK
+ * @module @edgespark/server-types
+ */
+import type { DrizzleD1Database } from "drizzle-orm/d1";
+import type { MiddlewareHandler } from "hono";
+/**
+ * EdgeSpark Client - main SDK entry point
+ * @template TSchema - Database schema from @generated
+ * @example
+ * export async function backend(app: Hono, edgespark: Client<typeof tables>) {
+ *   app.get('/api/users', async (c) => {
+ *     const users = await edgespark.db.select().from(tables.users);
+ *     return c.json({ users });
+ *   });
+ * }
+ */
+export interface Client<TSchema extends Record<string, unknown> = Record<string, never>> {
+    /** Drizzle D1 database client */
+    db: DrizzleD1Database<TSchema>;
+    /** Authentication client (Better Auth) */
+    auth: AuthClient;
+    /** File storage client (R2) */
+    storage: StorageClient;
+    /** Environment secrets (ES_USER_SECRET__* prefix) */
+    secret: SecretClient;
+}
+export interface AuthSession {
+    session: {
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        userId: string;
+        token: string;
+        expiresAt: string;
+        ipAddress?: string | null;
+        userAgent?: string | null;
+    };
+    user?: {
+        id: string;
+        createdAt: string;
+        updatedAt: string;
+        email: string;
+        emailVerified: boolean;
+        name: string;
+        image?: string | null;
+    };
+}
+export interface AuthClient {
+    /** Get current session. Returns null if not authenticated. */
+    getSession(): Promise<AuthSession | null>;
+    /**
+     * Hono middleware enforcing auth. Sets `c.get('auth')`.
+     * @example app.get('/api/me', edgespark.auth.middleware(), (c) => c.json(c.get('auth')));
+     */
+    middleware(): MiddlewareHandler;
+}
+export interface SecretClient {
+    /**
+     * Get secret by name. Reads from env.ES_USER_SECRET__{name}.
+     * @example const key = edgespark.secret.get('API_KEY');
+     */
+    get(name: string): string | null;
+}
+/** Bucket definition from @generated/storage_schema */
+export interface BucketDef {
+    readonly bucket_name: string;
+    readonly description: string;
+}
+export interface StorageClient {
+    /**
+     * Create storage URI for database storage
+     * @example const uri = edgespark.storage.toUri(buckets.avatars, 'user-1.jpg'); // "s3://avatars/user-1.jpg"
+     */
+    toUri(bucket: BucketDef, path: string): string;
+    /**
+     * Parse storage URI back to bucket + path
+     * @example const { bucket, path } = edgespark.storage.fromUri(user.avatarUri);
+     */
+    fromUri(uri: string): {
+        bucket: BucketDef;
+        path: string;
+    };
+    /**
+     * Select bucket for operations
+     * @example await edgespark.storage.from(buckets.uploads).put('file.txt', buffer);
+     */
+    from(bucket: BucketDef): BucketClient;
+}
+export interface BucketClient {
+    /**
+     * Upload file (<100MB). Use createPresignedPutUrl for large files.
+     * @example await bucket.put('photo.jpg', buffer, { contentType: 'image/jpeg' });
+     */
+    put(path: string, file: ArrayBuffer, options?: StorageHttpMetadata): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Download file. Returns null if not found.
+     * @example const file = await bucket.get('doc.pdf'); if (file) { ... }
+     */
+    get(path: string): Promise<StorageObject | null>;
+    /**
+     * Get metadata only (no body). Faster than get() for existence checks.
+     * @example const meta = await bucket.head('file.txt'); if (meta) { ... }
+     */
+    head(path: string): Promise<StorageObjectMetadata | null>;
+    /**
+     * List files with optional prefix filter
+     * @example const { objects, hasMore, cursor } = await bucket.list('user-123/');
+     */
+    list(prefix?: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<StorageListResult>;
+    /**
+     * Delete file(s). Supports bulk delete up to 1000 paths.
+     * @example await bucket.delete(['file1.jpg', 'file2.jpg']);
+     */
+    delete(paths: string | string[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Generate presigned upload URL for direct client uploads
+     * @example const { uploadUrl } = await bucket.createPresignedPutUrl('video.mp4', 3600);
+     */
+    createPresignedPutUrl(path: string, expiresInSecs?: number, options?: StorageHttpMetadata): Promise<{
+        uploadUrl: string;
+        path: string;
+        expiresAt: Date;
+    }>;
+    /**
+     * Generate presigned download URL for direct client downloads
+     * @example const { downloadUrl } = await bucket.createPresignedGetUrl('video.mp4', 3600);
+     */
+    createPresignedGetUrl(path: string, expiresInSecs?: number): Promise<{
+        downloadUrl: string;
+        path: string;
+        expiresAt: Date;
+    }>;
+}
+export interface StorageHttpMetadata {
+    contentType?: string;
+    contentDisposition?: string;
+    contentEncoding?: string;
+    cacheControl?: string;
+}
+export interface StorageObjectMetadata {
+    size: number;
+    httpMetadata: StorageHttpMetadata;
+}
+export interface StorageObject {
+    body: ArrayBuffer;
+    metadata: StorageObjectMetadata;
+}
+export interface StorageFileInfo {
+    key: string;
+    size: number;
+    uploaded: Date;
+}
+export interface StorageListResult {
+    objects: StorageFileInfo[];
+    hasMore: boolean;
+    cursor?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * @edgespark/server-types - Type definitions for EdgeSpark server SDK
+ * @module @edgespark/server-types
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@edgespark/server-types",
+  "version": "0.0.1-alpha.0",
+  "description": "Type definitions for EdgeSpark server SDK",
+  "keywords": [
+    "edgespark",
+    "cloudflare",
+    "workers",
+    "d1",
+    "r2",
+    "drizzle",
+    "hono",
+    "typescript",
+    "types"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.30.0",
+    "hono": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20251111.0",
+    "drizzle-orm": "^0.44.0",
+    "hono": "^4.10.0",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}