@sublay/js 5.0.0

package/CLAUDE.md

@@ -0,0 +1,339 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **@sublay/js** package - the official JavaScript SDK for Sublay. It's a lightweight, framework-agnostic SDK designed for JavaScript/TypeScript projects that don't use React or don't need the full React setup from the monorepo packages.
+
+**Package Name**: @sublay/js
+**Version**: 5.0.0
+**Type**: JavaScript SDK library (published to npm)
+
+## Development Commands
+
+```bash
+# Build the package (TypeScript compilation + bundling)
+pnpm build
+
+# Generate TypeScript declaration files
+pnpm build:types
+
+# Build both (runs before publishing)
+pnpm prepare
+
+# Publish to npm with beta tag
+pnpm publish-beta
+
+# Publish to npm production
+pnpm publish-prod
+```
+
+## Core Architecture
+
+### Module Structure
+
+The SDK is organized into 3 main API modules:
+
+```
+src/
+├── core/
+│   └── client.ts        # HTTP client wrapper using axios
+├── modules/
+│   ├── users/           # User operations (2 functions)
+│   │   ├── index.ts
+│   │   ├── fetchUserById.ts
+│   │   └── fetchUserByForeignId.ts
+│   ├── entities/        # Entity CRUD operations (7 functions)
+│   │   ├── index.ts
+│   │   ├── createEntity.ts
+│   │   ├── fetchEntity.ts
+│   │   ├── fetchEntityByForeignId.ts
+│   │   ├── fetchEntityByShortId.ts
+│   │   ├── fetchManyEntities.ts
+│   │   ├── updateEntity.ts
+│   │   └── deleteEntity.ts
+│   └── comments/        # Comment operations (2 functions)
+│       ├── index.ts
+│       ├── fetchComment.ts
+│       └── fetchCommentByForeignId.ts
+└── index.ts             # Main entry point with SublayClient class
+```
+
+### HTTP Client
+
+Uses a custom `SublayHttpClient` class that wraps axios with pre-configured base URL:
+- **Base URL**: `https://api.sublay.io/api/v5/{projectId}`
+- **Headers**: Standard axios configuration
+- **Method**: GET/POST/PUT/DELETE operations
+
+### Initialization Pattern
+
+```typescript
+import { SublayClient } from '@sublay/js';
+
+const client = await SublayClient.init({
+    projectId: "your-project-id"
+});
+
+// Client initializes and returns bound module functions
+```
+
+**Factory Pattern**: Uses `SublayClient.init()` for initialization, which:
+1. Creates an HTTP client instance with the project ID
+2. Binds all module functions to the client
+3. Returns the client with namespaced API methods
+
+## API Modules & Features
+
+### 1. Users Module (2 functions)
+
+**Functions**:
+- `client.users.fetchUserById({ userId })` - Fetch user by Sublay ID
+- `client.users.fetchUserByForeignId({ foreignId, name?, username?, avatar?, bio?, metadata?, secureMetadata? })` - Fetch user by external ID with optional user data
+
+**Features**:
+- Foreign ID support for external system integration
+- Optional user data creation on first fetch
+- Support for public and secure metadata
+
+### 2. Entities Module (7 functions)
+
+Entities are the core content objects (posts, articles, products, listings, etc.).
+
+**Functions**:
+- `client.entities.createEntity(data)` - Create a new entity
+- `client.entities.fetchEntity({ entityId })` - Fetch by Sublay ID
+- `client.entities.fetchEntityByForeignId({ foreignId })` - Fetch by external system ID
+- `client.entities.fetchEntityByShortId({ shortId })` - Fetch by short/shareable ID
+- `client.entities.fetchManyEntities(filters)` - Advanced querying with extensive filters
+- `client.entities.updateEntity(data)` - Update entity
+- `client.entities.deleteEntity({ entityId })` - Delete entity
+
+**Create Entity Parameters**:
+- `foreignId` - External system ID for integration
+- `sourceId` - Source identifier (e.g., "blog", "shop")
+- `title` - Entity title
+- `content` - Main content/body
+- `attachments` - Media attachments (flexible structure)
+- `keywords` - Tags/categories
+- `location` - Geo-location (lat/lng or GeoJSON Point)
+- `metadata` - Custom metadata (up to 10KB)
+- `userId` - Author/creator ID
+
+**Advanced Filtering** (fetchManyEntities):
+Supports extensive filtering options:
+- **Sorting**: `hot`, `top`, `controversial`
+- **Timeframes**: `hour`, `day`, `week`, `month`, `year`, `all`
+- **Pagination**: `page`, `limit`
+- **Keywords**:
+  - `keywords.includes` - Array of required tags
+  - `keywords.excludes` - Array of excluded tags
+- **Metadata Filters**:
+  - `metadata.includes` - Object of required key-value pairs
+  - `metadata.excludes` - Object of excluded key-value pairs
+  - `metadata.exists` - Array of required metadata keys
+- **Content Filters**:
+  - `title.includes` / `title.excludes` - Title text filtering
+  - `content.includes` / `content.excludes` - Content text filtering
+- **Attachment Filters**:
+  - `attachments.has` - Entities with attachments
+  - `attachments.hasNot` - Entities without attachments
+- **Location Filters**:
+  - `location.latitude` / `location.longitude` - Geo-coordinates
+  - `location.radius` - Radius in kilometers
+- **User Filters**:
+  - `userId` - Filter by specific user
+  - `followedOnly` - Only from users the current user follows
+
+### 3. Comments Module (2 functions)
+
+**Functions**:
+- `client.comments.fetchComment({ commentId })` - Fetch comment by Sublay ID
+- `client.comments.fetchCommentByForeignId({ foreignId })` - Fetch comment by external ID
+
+**Note**: This module currently provides read-only access. Comment creation/updates are available in other SDK packages (@sublay/node) or through direct API calls.
+
+## Key Design Patterns
+
+### 1. Framework-Agnostic
+No dependencies on React, Vue, Angular, or any specific framework. Works with vanilla JavaScript, TypeScript, or any JavaScript framework.
+
+### 2. Type Safety
+Full TypeScript support with type definitions, though return types are currently `any` with TODOs to add proper entity types in future versions.
+
+### 3. Function Binding
+Module functions are bound to the HTTP client at initialization, providing a clean API without manually passing the client.
+
+### 4. Foreign ID Support
+Seamless integration with existing systems through foreign ID mapping on all major resources.
+
+### 5. Location Flexibility
+Supports both simple `{ lat, lng }` objects and GeoJSON Point format for geo-location data.
+
+## Usage Examples
+
+### Basic Initialization
+
+```typescript
+import { SublayClient } from '@sublay/js';
+
+const client = await SublayClient.init({
+    projectId: 'your-project-id'
+});
+```
+
+### Fetching Entities
+
+```javascript
+// Fetch single entity
+const entity = await client.entities.fetchEntity({
+    entityId: 'entity-123'
+});
+
+// Fetch by foreign ID
+const post = await client.entities.fetchEntityByForeignId({
+    foreignId: 'blog-post-456'
+});
+
+// Fetch with advanced filters
+const trendingPosts = await client.entities.fetchManyEntities({
+    sort: 'hot',
+    timeframe: 'week',
+    keywords: { includes: ['javascript', 'tutorial'] },
+    attachments: { has: true },
+    limit: 20,
+    page: 1
+});
+```
+
+### Creating Entities
+
+```javascript
+const newEntity = await client.entities.createEntity({
+    foreignId: 'my-post-789',
+    sourceId: 'blog',
+    title: 'Getting Started with JavaScript',
+    content: 'In this tutorial, we will learn...',
+    keywords: ['javascript', 'tutorial', 'beginner'],
+    userId: 'user-123',
+    metadata: {
+        category: 'programming',
+        difficulty: 'beginner',
+        readTime: 5
+    }
+});
+```
+
+### Updating Entities
+
+```javascript
+await client.entities.updateEntity({
+    entityId: 'entity-123',
+    title: 'Updated Title',
+    content: 'Updated content...',
+    keywords: ['updated', 'tags']
+});
+```
+
+### Geo-Location Filtering
+
+```javascript
+// Find entities near a location
+const nearbyPosts = await client.entities.fetchManyEntities({
+    location: {
+        latitude: 40.7128,
+        longitude: -74.0060,
+        radius: 10  // 10km radius
+    },
+    limit: 50
+});
+```
+
+### Working with Users
+
+```javascript
+// Fetch user by ID
+const user = await client.users.fetchUserById({
+    userId: 'user-123'
+});
+
+// Fetch or create user by foreign ID
+const externalUser = await client.users.fetchUserByForeignId({
+    foreignId: 'external-user-456',
+    name: 'John Doe',
+    username: 'johndoe',
+    avatar: 'https://example.com/avatar.jpg',
+    metadata: {
+        source: 'external-system'
+    }
+});
+```
+
+## Build & Publishing
+
+### Build Configuration
+- **Build Tool**: tsup
+- **Output Formats**: CommonJS and ESM (dual package)
+- **Type Declarations**: Generated via TypeScript compiler
+- **Target**: Modern JavaScript (ES modules)
+- **Entry Point**: `src/index.ts`
+
+### Output Structure
+```
+dist/
+├── index.js         # Main bundle (CJS/ESM)
+└── index.d.ts       # TypeScript declarations
+```
+
+### Publishing
+```bash
+# Beta release
+pnpm publish-beta
+
+# Production release
+pnpm publish-prod
+```
+
+**Package Exports**:
+- Main: `dist/index.js`
+- Types: `dist/index.d.ts`
+
+## Use Cases
+
+This SDK is ideal for:
+
+1. **Vanilla JavaScript Projects** - Plain JS applications without frameworks
+2. **Non-React Frameworks** - Vue, Svelte, Angular, Solid, etc.
+3. **Server-Side Rendering** - SSR applications without React
+4. **Static Site Generators** - Eleventy, Hugo (with JavaScript), Astro (non-React)
+5. **Chrome Extensions** - Browser extensions built with vanilla JS
+6. **Electron Apps** - Desktop applications using web technologies
+7. **Web Workers** - Background scripts and service workers
+8. **Lightweight Integrations** - When you don't need the full React SDK overhead
+
+Essentially any JavaScript/TypeScript project that needs Sublay integration without React dependencies.
+
+## Technical Details
+
+- **TypeScript**: Strict mode enabled
+- **Dependencies**: Only axios for HTTP requests
+- **API Version**: Uses v5 API endpoints
+- **Bundle Size**: Lightweight (no framework dependencies)
+- **Browser Support**: Modern browsers (ES6+)
+- **Node.js Support**: Yes (v14+)
+
+## Important Notes
+
+- This SDK is **production-ready** (v5.0.0)
+- Requires a valid project ID from Sublay dashboard
+- Currently uses v5 API endpoints
+- Return types are typed as `any` (TODOs exist to add proper types)
+- No README.md file exists yet (documentation pending)
+- Comment module has limited functionality (read-only)
+
+## Comparison with Other SDKs
+
+- **vs @sublay/node**: This SDK is lighter weight and framework-agnostic, while @sublay/node is optimized for Node.js server environments with more comprehensive API coverage
+- **vs @sublay/react-js**: This SDK has no React dependencies, making it suitable for non-React projects or when you don't need React hooks and components
+- **vs monorepo packages**: This SDK is standalone and simpler, while monorepo packages provide full React/React Native integration with hooks, contexts, and UI components

package/README.md

@@ -0,0 +1,93 @@
+# @sublay/js
+
+[![npm](https://img.shields.io/npm/v/@sublay/js.svg)](https://www.npmjs.com/package/@sublay/js)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+> **Backend infrastructure for user-powered products.** Pre-modeled bundles for the layers every app ends up rebuilding — comments, notifications, files, search, chat, and more. Install what you need, call through one SDK. Build the part that's actually yours.
+
+Framework-agnostic JavaScript SDK for Sublay. For browser apps and JS runtimes that don't use React, or don't want the React provider tree.
+
+Exposes a single `SublayClient` with module namespaces for `users`, `entities`, and `comments`.
+
+```bash
+npm install @sublay/js
+```
+
+```ts
+import { SublayClient } from "@sublay/js";
+
+const sublay = await SublayClient.init({
+  projectId: "your-project-id",
+});
+
+const entities = await sublay.entities.list({ ... });
+```
+
+See [docs.sublay.io](https://docs.sublay.io) for the full reference.
+
+---
+
+## What is Sublay
+
+Every user-powered product runs into the same engineering problems — content modeling, threaded discussions, permission graphs, ranking pipelines, search indexing, notification fan-out, social graphs, and moderation queues. Sublay solves them, so you don't have to.
+
+Sublay ships these layers as **pre-modeled bundles** that attach to one shared entity model. You install the bundles you need from the dashboard, call them through any Sublay SDK, and build the part that's actually yours on top.
+
+## Bundles you can install
+
+- **Comments & Threads** — threaded discussions with mentions, replies, sorting
+- **Reactions & Votes** — upvotes, downvotes, multi-emoji reactions
+- **Spaces & Communities** — groups, sub-forums, membership
+- **Notifications** — in-app notification fan-out with optional webhook delivery
+- **Feeds & Discovery** — hot / top / new / controversial, filtered by tag, geography, timeframe, or follow graph
+- **Real-Time Chat** — direct messages and group threads
+- **Follows & Connections** — one-way follows, mutual connections
+- **Files & Storage** — file blob storage with managed upload URLs
+- **AI-Powered Search** — semantic search across your entity tree
+- **Moderation** — report queues and content-removal workflows
+
+Every bundle attaches to the same model. No mismatches, no extra databases. One schema for everything.
+
+## How it works
+
+1. Create a project at [dash.sublay.io](https://dash.sublay.io) and install the bundles you need.
+2. Install a Sublay SDK in your app — this one, or one of its siblings (see below).
+3. Optionally drop in the open-source [`@sublay/ui-core-*`](https://github.com/sublay/ui-core) primitives, or install full components via the Sublay CLI registry.
+
+## The Sublay dashboard
+
+The dashboard at [dash.sublay.io](https://dash.sublay.io) is a database/backend console for your project:
+
+- **Overview** — usage metrics and project health
+- **Authentication** — end users and OAuth providers
+- **Database** — schema browser (tables, relationships) and a table editor for browsing rows
+- **Storage** — file blobs uploaded through the Files bundle
+- **Reports** — moderation queue across entity and comment reports
+- **Broadcast** — send notifications to your users
+- **Settings** — domains, webhooks, integrations, members, secrets, billing
+
+## The Sublay SDK family
+
+- [`@sublay/core`](https://www.npmjs.com/package/@sublay/core) — platform-agnostic hooks and utilities
+- [`@sublay/react-js`](https://www.npmjs.com/package/@sublay/react-js) — React (web)
+- [`@sublay/react-native`](https://www.npmjs.com/package/@sublay/react-native) — React Native
+- [`@sublay/expo`](https://www.npmjs.com/package/@sublay/expo) — Expo with SecureStore token storage
+- [`@sublay/node`](https://www.npmjs.com/package/@sublay/node) — server-side Node.js (backends, server actions, webhook handlers)
+- [`@sublay/js`](https://www.npmjs.com/package/@sublay/js) — framework-agnostic JavaScript (browser apps without React)
+- [`@sublay/ui-core-react-js`](https://www.npmjs.com/package/@sublay/ui-core-react-js) / [`@sublay/ui-core-react-native`](https://www.npmjs.com/package/@sublay/ui-core-react-native) — open-source UI primitives
+
+## Documentation
+
+Full API reference, SDK guides, and recipes: **[docs.sublay.io](https://docs.sublay.io)**
+
+## Community & support
+
+- **Discord** — [discord.gg/REKxnCJzPz](https://discord.gg/REKxnCJzPz)
+- **Blog** — [blog.sublay.io](https://blog.sublay.io)
+- **X** — [@yantsab](https://x.com/yantsab)
+- **LinkedIn** — [linkedin.com/company/sublay](https://www.linkedin.com/company/sublay)
+- **Email** — [support@sublay.io](mailto:support@sublay.io)
+
+## License
+
+Apache 2.0

package/dist/core/client.d.ts

@@ -0,0 +1,8 @@
+import { AxiosInstance } from "axios";
+export interface ClientConfig {
+    projectId: string;
+}
+export declare class SublayHttpClient {
+    instance: AxiosInstance;
+    constructor({ projectId }: ClientConfig);
+}

package/dist/index.d.mts

@@ -0,0 +1,189 @@
+import { AxiosInstance } from 'axios';
+
+interface ClientConfig {
+    projectId: string;
+}
+declare class SublayHttpClient {
+    instance: AxiosInstance;
+    constructor({ projectId }: ClientConfig);
+}
+
+interface FetchUserByIdProps {
+    userId: string;
+}
+declare function fetchUserById(client: SublayHttpClient, data: FetchUserByIdProps): Promise<any>;
+
+interface FetchUserByForeignIdProps {
+    foreignId: string;
+    name?: string;
+    username?: string;
+    avatar?: string;
+    bio?: string;
+    metadata?: Record<string, any>;
+    secureMetadata?: Record<string, any>;
+}
+declare function fetchUserByForeignId(client: SublayHttpClient, data: FetchUserByForeignIdProps): Promise<any>;
+
+declare const Users_fetchUserByForeignId: typeof fetchUserByForeignId;
+declare const Users_fetchUserById: typeof fetchUserById;
+declare namespace Users {
+  export { Users_fetchUserByForeignId as fetchUserByForeignId, Users_fetchUserById as fetchUserById };
+}
+
+interface CreateEntityProps {
+    foreignId?: string;
+    sourceId?: string;
+    spaceId?: string;
+    title?: string;
+    content?: string;
+    attachments?: Record<string, any>[];
+    keywords?: string[];
+    location?: {
+        latitude: number;
+        longitude: number;
+    };
+    metadata?: Record<string, any>;
+    userId?: string;
+}
+declare function createEntity(client: SublayHttpClient, data: CreateEntityProps): Promise<any>;
+
+interface FetchEntityProps {
+    entityId: string;
+}
+declare function fetchEntity(client: SublayHttpClient, data: FetchEntityProps): Promise<any>;
+
+interface FetchEntityByForeignIdProps {
+    foreignId: string;
+    createIfNotFound?: boolean;
+}
+declare function fetchEntityByForeignId(client: SublayHttpClient, data: FetchEntityByForeignIdProps): Promise<any>;
+
+interface FetchEntityByShortIdProps {
+    shortId: string;
+}
+declare function fetchEntityByShortId(client: SublayHttpClient, data: FetchEntityByShortIdProps): Promise<any>;
+
+interface PaginationMetadata {
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    totalItems: number;
+    hasMore: boolean;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationMetadata;
+}
+
+interface KeywordsFilters {
+    includes?: string[];
+    doesNotInclude?: string[];
+}
+interface MetadataFilters {
+    includes?: {
+        [key: string]: any;
+    };
+    doesNotInclude?: {
+        [key: string]: any;
+    };
+    exists?: string[];
+    doesNotExist?: string[];
+}
+interface TextFilters {
+    hasTitle?: "true" | "false";
+    includes?: string | string[];
+    doesNotInclude?: string | string[];
+}
+interface AttachmentsFilters {
+    hasAttachments?: "true" | "false";
+}
+interface LocationFilters {
+    latitude: string;
+    longitude: string;
+    radius: string;
+}
+interface FetchManyEntitiesProps {
+    sourceId?: string;
+    spaceId?: string;
+    sortBy?: "hot" | "top" | "controversial";
+    page?: number;
+    limit?: number;
+    timeFrame?: "hour" | "day" | "week" | "month" | "year";
+    userId?: string;
+    followedOnly?: "true";
+    keywordsFilters?: KeywordsFilters;
+    metadataFilters?: MetadataFilters;
+    titleFilters?: TextFilters;
+    contentFilters?: {
+        hasContent?: "true" | "false";
+        includes?: string | string[];
+        doesNotInclude?: string | string[];
+    };
+    attachmentsFilters?: AttachmentsFilters;
+    locationFilters?: LocationFilters;
+}
+declare function fetchManyEntities(client: SublayHttpClient, data: FetchManyEntitiesProps): Promise<PaginatedResponse<any>>;
+
+interface UpdateEntityProps {
+    entityId: string;
+    title?: string;
+    content?: string;
+    attachments?: Record<string, any>[];
+    keywords?: string[];
+    location?: {
+        type: "Point";
+        coordinates: [number, number];
+    };
+    metadata?: Record<string, any>;
+    mentions?: {
+        id: string;
+        username: string;
+    }[];
+}
+declare function updateEntity(client: SublayHttpClient, data: UpdateEntityProps): Promise<any>;
+
+interface DeleteEntityProps {
+    entityId: string;
+}
+declare function deleteEntity(client: SublayHttpClient, data: DeleteEntityProps): Promise<any>;
+
+declare const Entities_createEntity: typeof createEntity;
+declare const Entities_deleteEntity: typeof deleteEntity;
+declare const Entities_fetchEntity: typeof fetchEntity;
+declare const Entities_fetchEntityByForeignId: typeof fetchEntityByForeignId;
+declare const Entities_fetchEntityByShortId: typeof fetchEntityByShortId;
+declare const Entities_fetchManyEntities: typeof fetchManyEntities;
+declare const Entities_updateEntity: typeof updateEntity;
+declare namespace Entities {
+  export { Entities_createEntity as createEntity, Entities_deleteEntity as deleteEntity, Entities_fetchEntity as fetchEntity, Entities_fetchEntityByForeignId as fetchEntityByForeignId, Entities_fetchEntityByShortId as fetchEntityByShortId, Entities_fetchManyEntities as fetchManyEntities, Entities_updateEntity as updateEntity };
+}
+
+interface FetchCommentProps {
+    commentId: string;
+}
+declare function fetchComment(client: SublayHttpClient, data: FetchCommentProps): Promise<any>;
+
+interface FetchCommentByForeignIdProps {
+    foreignId: string;
+}
+declare function fetchCommentByForeignId(client: SublayHttpClient, data: FetchCommentByForeignIdProps): Promise<any>;
+
+declare const Comments_fetchComment: typeof fetchComment;
+declare const Comments_fetchCommentByForeignId: typeof fetchCommentByForeignId;
+declare namespace Comments {
+  export { Comments_fetchComment as fetchComment, Comments_fetchCommentByForeignId as fetchCommentByForeignId };
+}
+
+type BoundModule<T extends Record<string, (client: SublayHttpClient, ...args: any[]) => any>> = {
+    [K in keyof T]: (...args: Parameters<T[K]> extends [any, ...infer R] ? R : never) => ReturnType<T[K]>;
+};
+declare class SublayClient {
+    private http;
+    users: BoundModule<typeof Users>;
+    entities: BoundModule<typeof Entities>;
+    comments: BoundModule<typeof Comments>;
+    private constructor();
+    static init(config: ClientConfig): Promise<SublayClient>;
+}
+
+export { type PaginatedResponse, type PaginationMetadata, SublayClient };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { SublayHttpClient, ClientConfig } from "./core/client";
+import * as Users from "./modules/users";
+import * as Entities from "./modules/entities";
+import * as Comments from "./modules/comments";
+type BoundModule<T extends Record<string, (client: SublayHttpClient, ...args: any[]) => any>> = {
+    [K in keyof T]: (...args: Parameters<T[K]> extends [any, ...infer R] ? R : never) => ReturnType<T[K]>;
+};
+export declare class SublayClient {
+    private http;
+    users: BoundModule<typeof Users>;
+    entities: BoundModule<typeof Entities>;
+    comments: BoundModule<typeof Comments>;
+    private constructor();
+    static init(config: ClientConfig): Promise<SublayClient>;
+}
+export type { PaginatedResponse, PaginationMetadata } from "./interfaces/IPaginatedResponse";