@bernierllc/content-storage-adapter 1.0.0

package/.eslintrc.json

@@ -0,0 +1,22 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "plugins": ["@typescript-eslint"],
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/explicit-function-return-type": "warn",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "no-console": "warn"
+  },
+  "env": {
+    "node": true,
+    "jest": true
+  }
+}

package/README.md

@@ -0,0 +1,350 @@
+# @bernierllc/content-storage-adapter
+
+Type-safe CRUD operations for content management with automatic soft-delete handling, version tracking, and optimistic locking.
+
+## Features
+
+- **Type-Safe CRUD Operations** - Fully typed content models with TypeScript strict mode
+- **Automatic Soft-Delete** - All deletes are logical (deleted_at timestamp)
+- **Optimistic Locking** - Concurrent edit detection via updated_at
+- **Version History** - Track content changes over time
+- **Unique Slug Generation** - SEO-friendly URLs with automatic uniqueness
+- **Advanced Filtering** - Search by status, type, date range, and more
+- **Batch Operations** - Bulk update, delete, and restore
+- **Pagination Support** - Efficient list operations with hasMore indicator
+
+## Installation
+
+```bash
+npm install @bernierllc/content-storage-adapter
+```
+
+## Dependencies
+
+- `@bernierllc/database-adapter-core` - Abstract database interface
+- `@bernierllc/slug-generator` - SEO-friendly URL generation
+
+## Usage
+
+### Basic CRUD Operations
+
+```typescript
+import { ContentStorageAdapter, ContentType, ContentStatus } from '@bernierllc/content-storage-adapter';
+import { PostgreSQLAdapter } from '@bernierllc/database-adapter-postgresql';
+
+// Initialize database adapter
+const dbAdapter = new PostgreSQLAdapter(config);
+await dbAdapter.connect();
+
+// Create storage adapter
+const storage = new ContentStorageAdapter(dbAdapter);
+
+// Create content
+const content = await storage.create({
+  userId: 'user-123',
+  title: 'My First Post',
+  body: 'Hello, world!',
+  excerpt: 'A brief introduction',
+  type: ContentType.BLOG,
+  status: ContentStatus.DRAFT
+});
+
+// Read content
+const retrieved = await storage.getById(content.id);
+const bySlug = await storage.getBySlug('my-first-post');
+
+// Update content
+const updated = await storage.update(content.id, {
+  status: ContentStatus.PUBLISHED,
+  publishedAt: new Date()
+});
+
+// Soft delete
+await storage.delete(content.id);
+
+// Restore deleted content
+const restored = await storage.restore(content.id);
+```
+
+### Optimistic Locking
+
+Prevent concurrent edit conflicts:
+
+```typescript
+const content = await storage.getById('content-id');
+
+try {
+  // Update with expected timestamp
+  const updated = await storage.update(
+    content.id,
+    { title: 'Updated Title' },
+    content.updatedAt
+  );
+} catch (error) {
+  if (error instanceof OptimisticLockError) {
+    // Content was modified by another user
+    console.error('Conflict detected! Reload and try again.');
+  }
+}
+```
+
+### Advanced Filtering
+
+```typescript
+import { IContentFilters } from '@bernierllc/content-storage-adapter';
+
+const filters: IContentFilters = {
+  userId: 'user-123',
+  status: [ContentStatus.PUBLISHED, ContentStatus.SCHEDULED],
+  type: ContentType.BLOG,
+  publishedAfter: new Date('2024-01-01'),
+  searchQuery: 'TypeScript',
+  limit: 20,
+  offset: 0,
+  orderBy: 'publishedAt',
+  orderDirection: 'DESC'
+};
+
+const result = await storage.list(filters);
+
+console.log(`Found ${result.total} items`);
+console.log(`Has more: ${result.hasMore}`);
+result.data.forEach(item => console.log(item.title));
+```
+
+### Batch Operations
+
+```typescript
+import { ContentBatchOperations } from '@bernierllc/content-storage-adapter';
+
+const batchOps = new ContentBatchOperations(storage);
+
+// Bulk update status
+const updated = await batchOps.bulkUpdateStatus(
+  ['id1', 'id2', 'id3'],
+  ContentStatus.ARCHIVED
+);
+console.log(`Updated ${updated} items`);
+
+// Bulk delete
+const deleted = await batchOps.bulkDelete(['id4', 'id5']);
+
+// Bulk restore
+const restored = await batchOps.bulkRestore(['id4', 'id5']);
+```
+
+### Version History
+
+```typescript
+// Get all versions
+const versions = await storage.getVersions('content-id');
+versions.forEach(v => {
+  console.log(`Version ${v.versionNumber}: ${v.title}`);
+  console.log(`Changed by ${v.createdBy} at ${v.createdAt}`);
+});
+
+// Get specific version
+const version2 = await storage.getVersion('content-id', 2);
+```
+
+## API
+
+### ContentStorageAdapter
+
+#### `create(data: IContentCreateData): Promise<IContent>`
+
+Create new content with automatic slug generation.
+
+#### `getById(id: string, options?: { includeDeleted?: boolean }): Promise<IContent | null>`
+
+Get content by ID. Excludes soft-deleted content by default.
+
+#### `getBySlug(slug: string): Promise<IContent | null>`
+
+Get content by URL slug.
+
+#### `update(id: string, data: IContentUpdateData, expectedUpdatedAt?: Date): Promise<IContent>`
+
+Update content. Optional `expectedUpdatedAt` enables optimistic locking.
+
+#### `delete(id: string): Promise<void>`
+
+Soft delete content (sets deleted_at timestamp).
+
+#### `hardDelete(id: string): Promise<void>`
+
+Permanently delete content. Use sparingly!
+
+#### `restore(id: string): Promise<IContent>`
+
+Restore soft-deleted content.
+
+#### `list(filters?: IContentFilters): Promise<IPaginatedResult<IContent>>`
+
+List content with filtering, pagination, and ordering.
+
+#### `getVersions(contentId: string): Promise<IContentVersion[]>`
+
+Get all versions of content, ordered by version number descending.
+
+#### `getVersion(contentId: string, versionNumber: number): Promise<IContentVersion | null>`
+
+Get specific content version.
+
+### ContentBatchOperations
+
+#### `bulkUpdateStatus(ids: string[], status: ContentStatus): Promise<number>`
+
+Update status for multiple content items. Returns count of updated items.
+
+#### `bulkDelete(ids: string[]): Promise<number>`
+
+Soft delete multiple items. Returns count of deleted items.
+
+#### `bulkRestore(ids: string[]): Promise<number>`
+
+Restore multiple soft-deleted items. Returns count of restored items.
+
+## Types
+
+### ContentType
+
+```typescript
+enum ContentType {
+  BLOG = 'blog',
+  ARTICLE = 'article',
+  PAGE = 'page',
+  SOCIAL = 'social'
+}
+```
+
+### ContentFormat
+
+```typescript
+enum ContentFormat {
+  MARKDOWN = 'markdown',
+  HTML = 'html',
+  PLAINTEXT = 'plaintext'
+}
+```
+
+### ContentStatus
+
+```typescript
+enum ContentStatus {
+  DRAFT = 'draft',
+  IN_REVIEW = 'in_review',
+  APPROVED = 'approved',
+  SCHEDULED = 'scheduled',
+  PUBLISHED = 'published',
+  ARCHIVED = 'archived'
+}
+```
+
+## Error Handling
+
+```typescript
+import {
+  ContentNotFoundError,
+  OptimisticLockError,
+  DuplicateSlugError
+} from '@bernierllc/content-storage-adapter';
+
+try {
+  await storage.update('invalid-id', { title: 'New Title' });
+} catch (error) {
+  if (error instanceof ContentNotFoundError) {
+    console.error('Content not found or already deleted');
+  } else if (error instanceof OptimisticLockError) {
+    console.error('Content was modified by another user');
+  }
+}
+```
+
+## Database Schema
+
+The adapter expects the following PostgreSQL schema:
+
+```sql
+CREATE TABLE content (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id VARCHAR(255) NOT NULL,
+  title TEXT NOT NULL,
+  slug VARCHAR(255) UNIQUE NOT NULL,
+  body TEXT NOT NULL,
+  excerpt TEXT,
+  type VARCHAR(50) NOT NULL,
+  format VARCHAR(50) NOT NULL,
+  status VARCHAR(50) NOT NULL,
+  workflow_stage VARCHAR(50),
+  assigned_to VARCHAR(255),
+  ai_reviewed BOOLEAN DEFAULT FALSE,
+  ai_review_score FLOAT,
+  ai_provider VARCHAR(100),
+  published_at TIMESTAMP,
+  scheduled_for TIMESTAMP,
+  deleted_at TIMESTAMP,
+  meta_title TEXT,
+  meta_description TEXT,
+  keywords TEXT[],
+  view_count INTEGER DEFAULT 0,
+  share_count INTEGER DEFAULT 0,
+  generated_from_commit BOOLEAN DEFAULT FALSE,
+  source_commit_sha VARCHAR(255),
+  source_repository VARCHAR(500),
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE content_versions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  content_id UUID NOT NULL REFERENCES content(id),
+  version_number INTEGER NOT NULL,
+  title TEXT NOT NULL,
+  body TEXT NOT NULL,
+  change_summary TEXT,
+  is_autosave BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  created_by VARCHAR(255) NOT NULL,
+  UNIQUE(content_id, version_number)
+);
+
+CREATE INDEX idx_content_user_id ON content(user_id);
+CREATE INDEX idx_content_slug ON content(slug);
+CREATE INDEX idx_content_status ON content(status);
+CREATE INDEX idx_content_deleted_at ON content(deleted_at);
+CREATE INDEX idx_content_versions_content_id ON content_versions(content_id);
+```
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests without watch
+npm run test:run
+
+# Run tests with coverage
+npm run test:coverage
+
+# Build TypeScript
+npm run build
+
+# Lint code
+npm run lint
+```
+
+## License
+
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+
+## Related Packages
+
+- [@bernierllc/database-adapter-core](../database-adapter-core) - Abstract database interface
+- [@bernierllc/slug-generator](../slug-generator) - SEO-friendly URL generation
+- [@bernierllc/content-storage-service](../../service/content-storage-service) - Higher-level storage orchestration

package/__tests__/ContentBatchOperations.test.ts

@@ -0,0 +1,130 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { ContentStorageAdapter } from '../src/ContentStorageAdapter';
+import { ContentBatchOperations } from '../src/ContentBatchOperations';
+import { ContentStatus, ContentType, ContentFormat } from '../src/models/IContent';
+import { MockDatabaseAdapter } from './mocks/MockDatabaseAdapter';
+import { IDatabaseAdapter } from '@bernierllc/database-adapter-core';
+
+describe('ContentBatchOperations', () => {
+  let batchOps: ContentBatchOperations;
+  let adapter: ContentStorageAdapter;
+  let dbAdapter: MockDatabaseAdapter;
+
+  beforeEach(async () => {
+    dbAdapter = new MockDatabaseAdapter();
+    await dbAdapter.connect();
+    adapter = new ContentStorageAdapter(dbAdapter as unknown as IDatabaseAdapter);
+    batchOps = new ContentBatchOperations(adapter);
+  });
+
+  afterEach(async () => {
+    await dbAdapter.disconnect();
+    dbAdapter.clearMocks();
+  });
+
+  describe('bulkUpdateStatus', () => {
+    it('should bulk update status', async () => {
+      const mockContent1 = {
+        id: '123',
+        user_id: 'user1',
+        title: 'Test Title',
+        slug: 'test-title',
+        body: 'Test body',
+        type: ContentType.BLOG,
+        format: ContentFormat.MARKDOWN,
+        status: ContentStatus.PUBLISHED,
+        ai_reviewed: false,
+        view_count: 0,
+        share_count: 0,
+        generated_from_commit: false,
+        created_at: new Date(),
+        updated_at: new Date()
+      };
+
+      // Mock each individual update query
+      dbAdapter.setQueryResult(
+        'update content set status = $1, updated_at = now() where id = $2 and deleted_at is null returning *',
+        { rows: [mockContent1], rowCount: 1 }
+      );
+
+      const result = await batchOps.bulkUpdateStatus(
+        ['123', '456', '789'],
+        ContentStatus.PUBLISHED
+      );
+
+      expect(result).toBe(3);
+    });
+
+    it('should handle partial failures gracefully', async () => {
+      // First update succeeds
+      dbAdapter.setQueryResult(
+        'update content set status = $1, updated_at = now() where id = $2 and deleted_at is null returning *',
+        { rows: [{ id: '123' }], rowCount: 1 }
+      );
+
+      const result = await batchOps.bulkUpdateStatus(
+        ['123', '456'],
+        ContentStatus.PUBLISHED
+      );
+
+      // Should continue even if some fail
+      expect(result).toBeGreaterThanOrEqual(0);
+      expect(result).toBeLessThanOrEqual(2);
+    });
+  });
+
+  describe('bulkDelete', () => {
+    it('should bulk delete', async () => {
+      dbAdapter.setQueryResult(
+        'UPDATE content SET deleted_at = NOW() WHERE id = ANY($1) AND deleted_at IS NULL',
+        { rows: [], rowCount: 3 }
+      );
+
+      const result = await batchOps.bulkDelete(['123', '456', '789']);
+
+      expect(result).toBe(3);
+    });
+
+    it('should return count of deleted items', async () => {
+      dbAdapter.setQueryResult(
+        'UPDATE content SET deleted_at = NOW() WHERE id = ANY($1) AND deleted_at IS NULL',
+        { rows: [], rowCount: 2 }
+      );
+
+      const result = await batchOps.bulkDelete(['123', '456']);
+
+      expect(result).toBe(2);
+    });
+  });
+
+  describe('bulkRestore', () => {
+    it('should bulk restore', async () => {
+      dbAdapter.setQueryResult(
+        'UPDATE content SET deleted_at = NULL WHERE id = ANY($1) AND deleted_at IS NOT NULL',
+        { rows: [], rowCount: 3 }
+      );
+
+      const result = await batchOps.bulkRestore(['123', '456', '789']);
+
+      expect(result).toBe(3);
+    });
+
+    it('should return count of restored items', async () => {
+      dbAdapter.setQueryResult(
+        'UPDATE content SET deleted_at = NULL WHERE id = ANY($1) AND deleted_at IS NOT NULL',
+        { rows: [], rowCount: 1 }
+      );
+
+      const result = await batchOps.bulkRestore(['123']);
+
+      expect(result).toBe(1);
+    });
+  });
+});