@natesena/blog-lib 0.1.0

package/dist/index-TnUz7zF0.d.ts

@@ -0,0 +1,404 @@
+import { PrismaClient, Author as Author$1, Tag as Tag$1 } from '@prisma/client';
+
+/**
+ * TypeScript types for Post
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md
+ */
+type Status = 'DRAFT' | 'PUBLISHED';
+interface TiptapContent {
+    type: string;
+    content?: unknown[];
+    attrs?: Record<string, unknown>;
+}
+interface CreatePostInput {
+    title: string;
+    content: string;
+    excerpt?: string;
+    coverImage?: string;
+    status?: Status;
+    authorId: string;
+    slug?: string;
+    tagIds?: string[];
+    publishedAt?: Date;
+}
+interface UpdatePostInput {
+    title?: string;
+    content?: string;
+    excerpt?: string;
+    coverImage?: string;
+    status?: Status;
+    tagIds?: string[];
+    publishedAt?: Date;
+}
+interface PostListFilters {
+    status?: Status;
+    authorId?: string;
+    tag?: string;
+    publishedBefore?: Date;
+    publishedAfter?: Date;
+    limit?: number;
+    offset?: number;
+}
+interface Post {
+    id: string;
+    slug: string;
+    title: string;
+    content: string;
+    excerpt: string | null;
+    coverImage: string | null;
+    status: Status;
+    publishedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    authorId: string;
+    tagIds: string[];
+}
+declare function isValidStatus(statusValue: string): statusValue is Status;
+
+/**
+ * TypeScript types for Author
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md
+ */
+interface CreateAuthorInput {
+    name: string;
+    email: string;
+    bio?: string;
+    avatar?: string;
+}
+interface UpdateAuthorInput {
+    name?: string;
+    bio?: string;
+    avatar?: string;
+}
+interface Author {
+    id: string;
+    name: string;
+    email: string;
+    bio: string | null;
+    avatar: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * TypeScript types for Tag
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md
+ */
+interface CreateTagInput {
+    name: string;
+    slug: string;
+    description?: string;
+}
+interface UpdateTagInput {
+    name?: string;
+    slug?: string;
+    description?: string;
+}
+interface Tag {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * Database Adapter Interface
+ *
+ * Defines the contract for all database adapters.
+ * Allows swapping between different databases (Postgres, SQLite, MongoDB, etc.)
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md
+ */
+
+interface DatabaseAdapter {
+    createPost(post: CreatePostInput): Promise<AdapterPost>;
+    getPost(id: string): Promise<AdapterPost | null>;
+    getPostBySlug(slug: string): Promise<AdapterPost | null>;
+    listPosts(filters?: PostListFilters): Promise<{
+        posts: AdapterPost[];
+        total: number;
+    }>;
+    updatePost(id: string, data: UpdatePostInput): Promise<AdapterPost>;
+    deletePost(id: string): Promise<void>;
+    createAuthor(author: CreateAuthorInput): Promise<Author>;
+    getAuthor(id: string): Promise<Author | null>;
+    getAuthorByEmail(email: string): Promise<Author | null>;
+    listAuthors(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Author[]>;
+    updateAuthor(id: string, data: UpdateAuthorInput): Promise<Author>;
+    deleteAuthor(id: string): Promise<void>;
+    createTag(tag: CreateTagInput): Promise<Tag>;
+    getTag(id: string): Promise<Tag | null>;
+    getTagBySlug(slug: string): Promise<Tag | null>;
+    listTags(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Tag[]>;
+    updateTag(id: string, data: UpdateTagInput): Promise<Tag>;
+    deleteTag(id: string): Promise<void>;
+}
+interface AdapterPost {
+    id: string;
+    slug: string;
+    title: string;
+    content: string;
+    excerpt: string | null;
+    coverImage: string | null;
+    status: 'DRAFT' | 'PUBLISHED';
+    publishedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    authorId: string;
+    tagIds: string[];
+    author?: Author | null;
+    tags?: Tag[] | null;
+}
+
+/**
+ * Posts SDK
+ *
+ * CRUD operations for blog posts, including filtering, slug lookup,
+ * and automatic slug generation.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 169-228)
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.4)
+ */
+
+declare class PostsSDK {
+    private adapter;
+    constructor(adapter: DatabaseAdapter);
+    /**
+     * Create a new blog post.
+     * Generates a slug from the title if none is provided.
+     * Auto-sets publishedAt when status is PUBLISHED.
+     */
+    create(input: CreatePostInput): Promise<AdapterPost>;
+    /** Get a post by its ID. */
+    get(id: string): Promise<AdapterPost | null>;
+    /** Get a post by its URL slug. */
+    getBySlug(slug: string): Promise<AdapterPost | null>;
+    /**
+     * List posts with optional filtering and pagination.
+     * Defaults to limit=10, offset=0.
+     */
+    list(filters?: PostListFilters): Promise<{
+        posts: AdapterPost[];
+        total: number;
+    }>;
+    /**
+     * Update an existing post by ID.
+     * Auto-sets publishedAt when transitioning from DRAFT to PUBLISHED.
+     */
+    update(id: string, data: UpdatePostInput): Promise<AdapterPost>;
+    /** Delete a post by ID. */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Authors SDK
+ *
+ * CRUD operations for blog authors.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 213-218)
+ * Ref: Plan Phase 5, Steps 5.3 and 5.4
+ */
+
+declare class AuthorsSDK {
+    private adapter;
+    constructor(adapter: DatabaseAdapter);
+    /** Create a new author. Email must be unique. */
+    create(input: CreateAuthorInput): Promise<Author>;
+    /** Get an author by their ID. */
+    get(id: string): Promise<Author | null>;
+    /** Get an author by their email address. */
+    getByEmail(email: string): Promise<Author | null>;
+    /** List authors with optional pagination. */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Author[]>;
+    /** Update an author by ID. */
+    update(id: string, data: UpdateAuthorInput): Promise<Author>;
+    /** Delete an author by ID. */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Tags SDK
+ *
+ * CRUD operations for blog tags.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 220-225)
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.14)
+ */
+
+declare class TagsSDK {
+    private adapter;
+    constructor(adapter: DatabaseAdapter);
+    /** Create a new tag. Name and slug must be provided and unique. */
+    create(input: CreateTagInput): Promise<Tag>;
+    /** Get a tag by its ID. */
+    get(id: string): Promise<Tag | null>;
+    /** Get a tag by its URL slug. */
+    getBySlug(slug: string): Promise<Tag | null>;
+    /** List tags with optional pagination. */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Tag[]>;
+    /** Update a tag by ID. */
+    update(id: string, data: UpdateTagInput): Promise<Tag>;
+    /** Delete a tag by ID. */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Postgres Adapter (Prisma)
+ *
+ * Implementation of DatabaseAdapter using Prisma ORM for PostgreSQL.
+ * Handles all CRUD operations with proper error handling and validation.
+ */
+
+declare class PostgresAdapter implements DatabaseAdapter {
+    private prisma;
+    constructor(prisma: PrismaClient);
+    createPost(post: CreatePostInput): Promise<AdapterPost>;
+    getPost(id: string): Promise<AdapterPost | null>;
+    getPostBySlug(slug: string): Promise<AdapterPost | null>;
+    listPosts(filters?: PostListFilters): Promise<{
+        posts: AdapterPost[];
+        total: number;
+    }>;
+    updatePost(id: string, data: UpdatePostInput): Promise<AdapterPost>;
+    deletePost(id: string): Promise<void>;
+    createAuthor(author: CreateAuthorInput): Promise<Author$1>;
+    getAuthor(id: string): Promise<Author$1 | null>;
+    getAuthorByEmail(email: string): Promise<Author$1 | null>;
+    listAuthors(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Author$1[]>;
+    updateAuthor(id: string, data: UpdateAuthorInput): Promise<Author$1>;
+    deleteAuthor(id: string): Promise<void>;
+    createTag(tag: CreateTagInput): Promise<Tag$1>;
+    getTag(id: string): Promise<Tag$1 | null>;
+    getTagBySlug(slug: string): Promise<Tag$1 | null>;
+    listTags(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Tag$1[]>;
+    updateTag(id: string, data: UpdateTagInput): Promise<Tag$1>;
+    deleteTag(id: string): Promise<void>;
+}
+
+/**
+ * Google Cloud Storage Integration
+ *
+ * Handles presigned URL generation, file deletion, and existence checks
+ * for image uploads to GCS.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 866-923)
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.9)
+ */
+interface GCSStorageConfig {
+    projectId: string;
+    bucket: string;
+    keyFile?: string;
+    /**
+     * 'public' (default) — files are publicly readable via direct URL.
+     * 'private' — files require a v4 signed read URL to access.
+     *
+     * Ref: Plan Phase 5, Step 5.5
+     */
+    accessMode?: 'public' | 'private';
+    /** How long signed read URLs last in seconds (default 3600 = 1 hour). Only used when accessMode is 'private'. */
+    signedReadUrlExpiresInSeconds?: number;
+}
+interface PresignedUploadResult {
+    uploadUrl: string;
+    /** Direct public URL when accessMode='public', or a v4 signed read URL when accessMode='private'. */
+    publicUrl: string;
+}
+declare class GCSStorage {
+    private storage;
+    private storageInitPromise;
+    private bucketName;
+    private accessMode;
+    private signedReadUrlExpiresInSeconds;
+    constructor(config: GCSStorageConfig);
+    private getStorage;
+    /**
+     * Generate a presigned URL for direct browser upload to GCS.
+     *
+     * @param filename - Destination path in bucket (e.g. "blog/posts/1234-abc.jpg")
+     * @param contentType - MIME type (e.g. "image/jpeg")
+     * @param uploadUrlExpiresInSeconds - URL expiry (default 300 = 5 min)
+     */
+    getPresignedUploadUrl(filename: string, contentType: string, uploadUrlExpiresInSeconds?: number): Promise<PresignedUploadResult>;
+    /**
+     * Get a read URL for an existing file.
+     * Returns a direct public URL or a v4 signed URL depending on accessMode.
+     */
+    getReadUrl(filename: string): Promise<string>;
+    /** Delete a file from GCS. */
+    delete(filename: string): Promise<void>;
+    /** Check if a file exists in the bucket. */
+    exists(filename: string): Promise<boolean>;
+}
+
+/**
+ * BlogSDK — Main Entry Point
+ *
+ * Initialize with a database adapter to get full CRUD for posts, authors, and tags.
+ *
+ * @example
+ * const blog = new BlogSDK(new PostgresAdapter(prisma));
+ * const post = await blog.posts.create({ title: "Hello", content: "...", authorId: "..." });
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 169-228)
+ */
+
+interface BlogSDKConfig {
+    adapter: DatabaseAdapter;
+    gcs?: {
+        bucket: string;
+        projectId: string;
+        keyFile?: string;
+        /** 'public' (default) or 'private' — private uses signed read URLs. */
+        accessMode?: 'public' | 'private';
+        /** Signed read URL expiry in seconds (default 3600). Only used when accessMode is 'private'. */
+        signedReadUrlExpiresInSeconds?: number;
+    };
+}
+declare class BlogSDK {
+    readonly posts: PostsSDK;
+    readonly authors: AuthorsSDK;
+    readonly tags: TagsSDK;
+    private adapter;
+    private gcsStorage?;
+    constructor(config: BlogSDKConfig);
+    /**
+     * Static factory method for initialization.
+     * Validates config and returns a ready-to-use BlogSDK instance.
+     */
+    static initialize(config: BlogSDKConfig): Promise<BlogSDK>;
+    /**
+     * Upload an image to GCS. Requires gcs config in BlogSDKConfig.
+     * Returns { uploadUrl, publicUrl } — client uploads directly to uploadUrl.
+     */
+    getImageUploadUrl(filename: string, contentType: string, options?: {
+        folder?: string;
+    }): Promise<{
+        uploadUrl: string;
+        publicUrl: string;
+    }>;
+}
+
+export { type AdapterPost as A, BlogSDK as B, type CreateAuthorInput as C, type DatabaseAdapter as D, GCSStorage as G, type Post as P, type Status as S, type Tag as T, type UpdateAuthorInput as U, type Author as a, type BlogSDKConfig as b, type CreatePostInput as c, type CreateTagInput as d, type GCSStorageConfig as e, type PostListFilters as f, PostgresAdapter as g, type TiptapContent as h, type UpdatePostInput as i, type UpdateTagInput as j, isValidStatus as k, AuthorsSDK as l, PostsSDK as m, TagsSDK as n };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { A as AdapterPost, a as Author, B as BlogSDK, b as BlogSDKConfig, C as CreateAuthorInput, c as CreatePostInput, d as CreateTagInput, D as DatabaseAdapter, G as GCSStorage, e as GCSStorageConfig, P as Post, f as PostListFilters, g as PostgresAdapter, S as Status, T as Tag, h as TiptapContent, U as UpdateAuthorInput, i as UpdatePostInput, j as UpdateTagInput, k as isValidStatus } from './index-TnUz7zF0.js';
+import '@prisma/client';
+
+/**
+ * BlogLibError — Custom Error Class
+ *
+ * Provides structured error codes for programmatic error handling.
+ * Consumers can catch BlogLibError and switch on the `code` field.
+ *
+ * Ref: Plan Phase 5, Step 5.3
+ */
+type BlogLibErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'DUPLICATE' | 'RELATION_ERROR' | 'STORAGE_ERROR' | 'AUTH_ERROR';
+declare class BlogLibError extends Error {
+    readonly code: BlogLibErrorCode;
+    constructor(code: BlogLibErrorCode, message: string);
+}
+
+export { BlogLibError, type BlogLibErrorCode };

package/dist/index.js

@@ -0,0 +1,21 @@
+import {
+  BlogLibError,
+  BlogSDK,
+  PostgresAdapter
+} from "./chunk-EG563RZL.js";
+import {
+  GCSStorage
+} from "./chunk-OPJV2ECE.js";
+
+// src/types/post.ts
+function isValidStatus(statusValue) {
+  return statusValue === "DRAFT" || statusValue === "PUBLISHED";
+}
+export {
+  BlogLibError,
+  BlogSDK,
+  GCSStorage,
+  PostgresAdapter,
+  isValidStatus
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types/post.ts"],"sourcesContent":["/**\n * TypeScript types for Post\n *\n * Ref: docs/epic-blog-lib/02-architecture.md\n */\n\n// Post Status\nexport type Status = 'DRAFT' | 'PUBLISHED';\n\n// Tiptap JSON content structure\nexport interface TiptapContent {\n  type: string;\n  content?: unknown[];\n  attrs?: Record<string, unknown>;\n}\n\n// Create Post Input\nexport interface CreatePostInput {\n  title: string;\n  content: string;\n  excerpt?: string;\n  coverImage?: string;\n  status?: Status;\n  authorId: string;\n  slug?: string;\n  tagIds?: string[];\n  publishedAt?: Date;\n}\n\n// Update Post Input (all fields optional)\nexport interface UpdatePostInput {\n  title?: string;\n  content?: string;\n  excerpt?: string;\n  coverImage?: string;\n  status?: Status;\n  tagIds?: string[];\n  publishedAt?: Date;\n}\n\n// Post List Filters\nexport interface PostListFilters {\n  status?: Status;\n  authorId?: string;\n  tag?: string;\n  publishedBefore?: Date;\n  publishedAfter?: Date;\n  limit?: number;\n  offset?: number;\n}\n\n// Post (from database)\nexport interface Post {\n  id: string;\n  slug: string;\n  title: string;\n  content: string;\n  excerpt: string | null;\n  coverImage: string | null;\n  status: Status;\n  publishedAt: Date | null;\n  createdAt: Date;\n  updatedAt: Date;\n  authorId: string;\n  tagIds: string[];\n}\n\n// Type guard for status\nexport function isValidStatus(statusValue: string): statusValue is Status {\n  return statusValue === 'DRAFT' || statusValue === 'PUBLISHED';\n}\n"],"mappings":";;;;;;;;;;AAoEO,SAAS,cAAc,aAA4C;AACxE,SAAO,gBAAgB,WAAW,gBAAgB;AACpD;","names":[]}

package/dist/sdk/index.d.ts

@@ -0,0 +1,2 @@
+export { A as AdapterPost, l as AuthorsSDK, B as BlogSDK, b as BlogSDKConfig, D as DatabaseAdapter, G as GCSStorage, e as GCSStorageConfig, g as PostgresAdapter, m as PostsSDK, n as TagsSDK } from '../index-TnUz7zF0.js';
+import '@prisma/client';

package/dist/sdk/index.js

@@ -0,0 +1,19 @@
+import {
+  AuthorsSDK,
+  BlogSDK,
+  PostgresAdapter,
+  PostsSDK,
+  TagsSDK
+} from "../chunk-EG563RZL.js";
+import {
+  GCSStorage
+} from "../chunk-OPJV2ECE.js";
+export {
+  AuthorsSDK,
+  BlogSDK,
+  GCSStorage,
+  PostgresAdapter,
+  PostsSDK,
+  TagsSDK
+};
+//# sourceMappingURL=index.js.map

package/dist/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pluggable Auth Configuration
+ *
+ * Allows consumers to inject their own auth provider into blog-lib.
+ * Upload actions and other protected operations call getCurrentUser()
+ * and reject requests if no user is returned.
+ *
+ * @example
+ * import { configureBlogAuth } from '@nate/blog-lib/server';
+ *
+ * configureBlogAuth({
+ *   getCurrentUser: async () => {
+ *     const session = await auth(); // your auth provider
+ *     return session?.user ?? null;
+ *   },
+ * });
+ *
+ * Ref: Plan Phase 3, Step 3.2
+ */
+interface BlogAuthUser {
+    id: string;
+    email?: string;
+}
+interface BlogAuthConfig {
+    /**
+     * Return the currently authenticated user, or null if unauthenticated.
+     * Called by upload actions and other protected operations.
+     */
+    getCurrentUser: () => Promise<BlogAuthUser | null>;
+}
+/**
+ * Configure blog-lib's auth integration. Call once during app initialization.
+ */
+declare function configureBlogAuth(config: BlogAuthConfig): void;
+
+/**
+ * Auth Permission Utilities
+ *
+ * Pluggable permission checks for CMS access.
+ * Works with any auth system — Clerk, Auth0, NextAuth.js, or custom.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 308-324)
+ * Ref: docs/epic-blog-lib/04-auth-guide.md
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.7)
+ */
+interface AuthUser {
+    id: string;
+    email: string;
+    isAdmin?: boolean;
+}
+/**
+ * Check if a user has permission to access the CMS.
+ *
+ * Uses CMS_ADMIN_EMAILS env var (comma-separated) to restrict access.
+ * If no env var is set, all authenticated users are allowed.
+ */
+declare function canAccessCMS(user: AuthUser): boolean;
+
+/**
+ * Simple API Key Auth
+ *
+ * For headless CMS access or simple auth without a full auth provider.
+ * Set CMS_API_KEY env var and send it in the x-api-key header.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 646-671)
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.7)
+ */
+/**
+ * Verify an API key against the CMS_API_KEY environment variable.
+ * Returns false if CMS_API_KEY is not configured.
+ */
+declare function verifyApiKey(providedApiKey?: string | null): boolean;
+/**
+ * Check the incoming request's x-api-key header against CMS_API_KEY.
+ * Use in server components or API routes.
+ */
+declare function checkApiKeyAuth(): Promise<boolean>;
+
+/**
+ * Auth Middleware Helper
+ *
+ * Convenience function to enforce auth in server components.
+ * Redirects unauthenticated users and checks CMS permissions.
+ *
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.7)
+ */
+
+/**
+ * Require authenticated CMS access. Redirects to signInUrl if no user,
+ * throws Error if user lacks CMS permission.
+ *
+ * @example
+ * const user = await getYourAuthUser();
+ * await requireCMSAuth(user, '/sign-in');
+ */
+declare function requireCMSAuth(user: AuthUser | null, signInRedirectUrl?: string): Promise<void>;
+
+/**
+ * Image Upload Server Actions
+ *
+ * Server-side actions for initiating and confirming image uploads to GCS.
+ * Frontend calls these, then uploads directly to GCS using the presigned URL.
+ *
+ * Ref: docs/epic-blog-lib/02-architecture.md (lines 927-991)
+ * Ref: docs/epic-blog-lib/03-tasks.md (Task openclaw-n1y.10)
+ */
+interface InitiateUploadInput {
+    fileName: string;
+    fileType: string;
+    fileSizeBytes: number;
+    folder?: string;
+}
+interface InitiateUploadResult {
+    uploadUrl: string;
+    publicUrl: string;
+    destinationFilename: string;
+}
+/**
+ * Validate the file and generate a presigned GCS upload URL.
+ * The client then uploads directly to GCS using this URL.
+ */
+declare function initiateImageUpload(input: InitiateUploadInput): Promise<InitiateUploadResult>;
+/**
+ * Confirm that a file was successfully uploaded to GCS.
+ * Call after the client finishes the direct upload.
+ */
+declare function confirmImageUpload(destinationFilename: string): Promise<{
+    isUploadConfirmed: boolean;
+}>;
+
+export { type AuthUser, type BlogAuthConfig, type BlogAuthUser, type InitiateUploadInput, type InitiateUploadResult, canAccessCMS, checkApiKeyAuth, configureBlogAuth, confirmImageUpload, initiateImageUpload, requireCMSAuth, verifyApiKey };