@denlabs/feedback-client 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @denlabs/feedback-client
+
+Typed client for the [DenLabs Event Feedback Ops](https://feedback-ops.vercel.app) API.
+
+Zero runtime dependencies — uses native `fetch`.
+
+## Install
+
+```bash
+pnpm add @denlabs/feedback-client
+```
+
+## Usage
+
+```typescript
+import { FeedbackClient } from '@denlabs/feedback-client'
+
+const client = new FeedbackClient({
+  baseUrl: 'https://feedback-ops.vercel.app',
+  adminToken: process.env.EFO_ADMIN_TOKEN, // required for admin endpoints
+})
+
+// List labs
+const { data: labs, meta } = await client.listLabs({ limit: 10 })
+
+// Get a lab
+const { data: lab } = await client.getLab('my-lab')
+
+// Submit feedback (public, no admin token needed)
+const publicClient = new FeedbackClient({
+  baseUrl: 'https://feedback-ops.vercel.app',
+})
+const { data: feedback } = await publicClient.submitFeedback('my-lab', {
+  message: 'The onboarding flow is confusing',
+  tags: ['ux', 'onboarding'],
+  route: '/labs/my-lab',
+})
+
+// Create a lab (admin)
+const { data: newLab } = await client.createLab({
+  name: 'ETH Denver 2026',
+  startDate: '2026-02-23T00:00:00Z',
+  endDate: '2026-03-02T00:00:00Z',
+  surfacesToObserve: ['registration', 'schedule', 'networking'],
+})
+
+// Triage feedback (admin)
+const { data: triaged } = await client.triageFeedback('my-lab', feedback.id, {
+  status: 'triaged',
+  priority: 'P1',
+})
+```
+
+## Error Handling
+
+```typescript
+import { FeedbackClient, FeedbackClientError } from '@denlabs/feedback-client'
+
+try {
+  await client.getLab('nonexistent')
+} catch (err) {
+  if (err instanceof FeedbackClientError) {
+    console.log(err.code)    // 'NOT_FOUND'
+    console.log(err.status)  // 404
+    console.log(err.message) // 'Lab not found'
+  }
+}
+```
+
+## Error Codes
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `VALIDATION_ERROR` | 400 | Invalid request parameters |
+| `UNAUTHORIZED` | 401 | Missing or invalid admin token |
+| `NOT_FOUND` | 404 | Resource not found |
+| `LAB_NOT_ACTIVE` | 409 | Lab is not accepting feedback |
+| `SLUG_EXHAUSTED` | 409 | Could not generate unique slug |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Server error |
+
+## API Reference
+
+| Method | Auth | Description |
+|--------|------|-------------|
+| `listLabs(opts?)` | Public | Paginated list of labs |
+| `createLab(input)` | Admin | Create a new lab |
+| `getLab(slug)` | Public | Get lab by slug |
+| `updateLabStatus(slug, input)` | Admin | Update lab status |
+| `listFeedback(slug, opts?)` | Public | Paginated feedback for a lab |
+| `submitFeedback(slug, input)` | Public | Submit feedback |
+| `triageFeedback(slug, id, input)` | Admin | Triage feedback |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import type { FeedbackClientConfig, Lab, FeedbackItem, FeedbackItemDetail, PublicFeedbackItem, PaginationMeta, CreateLabInput, UpdateLabStatusInput, CreateFeedbackInput, TriageFeedbackInput, PaginationInput, ListFeedbackInput } from './types.js';
+export declare class FeedbackClientError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(code: string, message: string, status: number, details?: unknown | undefined);
+}
+type DataResult<T> = {
+    data: T;
+};
+type ListResult<T> = {
+    data: T[];
+    meta: PaginationMeta;
+};
+export declare class FeedbackClient {
+    private readonly baseUrl;
+    private readonly adminToken?;
+    private readonly _fetch;
+    constructor(config: FeedbackClientConfig);
+    listLabs(opts?: PaginationInput): Promise<ListResult<Lab>>;
+    createLab(input: CreateLabInput): Promise<DataResult<Lab>>;
+    getLab(slug: string): Promise<DataResult<Lab>>;
+    updateLabStatus(slug: string, input: UpdateLabStatusInput): Promise<DataResult<Lab>>;
+    listFeedback(slug: string, opts?: ListFeedbackInput): Promise<ListResult<PublicFeedbackItem>>;
+    submitFeedback(slug: string, input: CreateFeedbackInput): Promise<DataResult<FeedbackItem>>;
+    triageFeedback(slug: string, id: string, input: TriageFeedbackInput): Promise<DataResult<FeedbackItemDetail>>;
+    private request;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,83 @@
+export class FeedbackClientError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'FeedbackClientError';
+    }
+}
+export class FeedbackClient {
+    baseUrl;
+    adminToken;
+    _fetch;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.adminToken = config.adminToken;
+        this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    // --- Labs ---
+    async listLabs(opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set('limit', String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set('offset', String(opts.offset));
+        const qs = params.toString();
+        return this.request('GET', `/api/labs${qs ? `?${qs}` : ''}`);
+    }
+    async createLab(input) {
+        return this.request('POST', '/api/labs', input, true);
+    }
+    async getLab(slug) {
+        return this.request('GET', `/api/labs/${encodeURIComponent(slug)}`);
+    }
+    async updateLabStatus(slug, input) {
+        return this.request('PATCH', `/api/labs/${encodeURIComponent(slug)}`, input, true);
+    }
+    // --- Feedback ---
+    async listFeedback(slug, opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set('limit', String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set('offset', String(opts.offset));
+        if (opts?.status)
+            params.set('status', opts.status);
+        const qs = params.toString();
+        return this.request('GET', `/api/labs/${encodeURIComponent(slug)}/feedback${qs ? `?${qs}` : ''}`);
+    }
+    async submitFeedback(slug, input) {
+        return this.request('POST', `/api/labs/${encodeURIComponent(slug)}/feedback`, input);
+    }
+    async triageFeedback(slug, id, input) {
+        return this.request('PATCH', `/api/labs/${encodeURIComponent(slug)}/feedback/${encodeURIComponent(id)}`, input, true);
+    }
+    // --- Internal ---
+    async request(method, path, body, requireAdmin = false) {
+        const headers = {};
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (requireAdmin) {
+            if (!this.adminToken) {
+                throw new FeedbackClientError('UNAUTHORIZED', 'Admin token required', 401);
+            }
+            headers['X-Admin-Token'] = this.adminToken;
+        }
+        const res = await this._fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const json = await res.json();
+        if (!res.ok) {
+            const err = json.error;
+            throw new FeedbackClientError(err?.code ?? 'UNKNOWN', err?.message ?? res.statusText, res.status, err?.details);
+        }
+        return json;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FeedbackClient, FeedbackClientError } from './client.js';
+export type { FeedbackClientConfig, Lab, LabStatus, FeedbackItem, FeedbackItemDetail, PublicFeedbackItem, FeedbackStatus, FeedbackPriority, ErrorCode, PaginationMeta, ApiError, ApiDataResponse, ApiErrorResponse, ApiResponse, CreateLabInput, UpdateLabStatusInput, CreateFeedbackInput, TriageFeedbackInput, PaginationInput, ListFeedbackInput, } from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { FeedbackClient, FeedbackClientError } from './client.js';

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+export type LabStatus = 'active' | 'paused' | 'completed' | 'archived';
+export type FeedbackStatus = 'new' | 'triaged' | 'done' | 'spam';
+export type FeedbackPriority = 'P0' | 'P1' | 'P2' | 'P3';
+export type ErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'UNAUTHORIZED' | 'RATE_LIMITED' | 'CONFLICT' | 'LAB_NOT_ACTIVE' | 'SLUG_EXHAUSTED' | 'INTERNAL_ERROR';
+export type Lab = {
+    id: string;
+    slug: string;
+    name: string;
+    objective: string | null;
+    surfaces_to_observe: string[];
+    status: LabStatus;
+    start_date: string;
+    end_date: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+};
+export type FeedbackItem = {
+    id: string;
+    message: string;
+    status: FeedbackStatus;
+    tags: string[];
+    created_at: string;
+};
+export type FeedbackItemDetail = {
+    id: string;
+    lab_id: string;
+    message: string;
+    status: FeedbackStatus;
+    priority: FeedbackPriority | null;
+    tags: string[];
+    route: string | null;
+    step: string | null;
+    event_type: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+};
+export type PublicFeedbackItem = {
+    id: string;
+    lab_slug: string;
+    message: string;
+    status: FeedbackStatus;
+    tags: string[];
+    created_at: string;
+};
+export type PaginationMeta = {
+    total: number;
+    limit: number;
+    offset: number;
+};
+export type ApiError = {
+    code: ErrorCode;
+    message: string;
+    details?: unknown;
+};
+export type ApiDataResponse<T> = {
+    data: T;
+    meta?: PaginationMeta;
+};
+export type ApiErrorResponse = {
+    error: ApiError;
+};
+export type ApiResponse<T> = ApiDataResponse<T> | ApiErrorResponse;
+export type CreateLabInput = {
+    name: string;
+    objective?: string | null;
+    surfacesToObserve?: string[];
+    startDate: string;
+    endDate?: string | null;
+    metadata?: Record<string, unknown>;
+};
+export type UpdateLabStatusInput = {
+    status: LabStatus;
+};
+export type CreateFeedbackInput = {
+    message: string;
+    tags?: string[];
+    route?: string;
+    step?: string;
+    eventType?: string;
+    metadata?: Record<string, unknown>;
+};
+export type TriageFeedbackInput = {
+    status?: FeedbackStatus;
+    priority?: FeedbackPriority | null;
+};
+export type PaginationInput = {
+    limit?: number;
+    offset?: number;
+};
+export type ListFeedbackInput = PaginationInput & {
+    status?: FeedbackStatus;
+};
+export type FeedbackClientConfig = {
+    baseUrl: string;
+    adminToken?: string;
+    fetch?: typeof globalThis.fetch;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+// --- Enums ---
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@denlabs/feedback-client",
+  "version": "0.1.0",
+  "description": "Typed client for the DenLabs Event Feedback Ops API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": ["denlabs", "feedback", "api-client"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.0"
+  }
+}