@sublay/js 5.0.0 → 7.0.0

package/CLAUDE.md

@@ -1,339 +0,0 @@
-# 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/pnpm-workspace.yaml

@@ -1,2 +0,0 @@
-allowBuilds:
-  esbuild: true

package/src/core/client.ts

@@ -1,15 +0,0 @@
-import axios, { AxiosInstance } from "axios";
-
-export interface ClientConfig {
-  projectId: string;
-}
-
-export class SublayHttpClient {
-  instance: AxiosInstance;
-
-  constructor({ projectId }: ClientConfig) {
-    this.instance = axios.create({
-      baseURL: `https://api.sublay.io/api/v5/${projectId}`,
-    });
-  }
-}

package/src/index.ts

@@ -1,45 +0,0 @@
-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 class SublayClient {
-  private http: SublayHttpClient;
-
-  public users: BoundModule<typeof Users>;
-  public entities: BoundModule<typeof Entities>;
-  public comments: BoundModule<typeof Comments>;
-
-  private constructor(http: SublayHttpClient) {
-    this.http = http;
-    this.users = bindModule(Users, this.http);
-    this.entities = bindModule(Entities, this.http);
-    this.comments = bindModule(Comments, this.http);
-  }
-
-  static async init(config: ClientConfig): Promise<SublayClient> {
-    const http = new SublayHttpClient(config);
-    return new SublayClient(http);
-  }
-}
-
-function bindModule<
-  T extends Record<string, (client: SublayHttpClient, ...args: any[]) => any>
->(module: T, client: SublayHttpClient): BoundModule<T> {
-  const bound: any = {};
-  for (const key in module) {
-    bound[key] = (...args: any[]) => module[key](client, ...args);
-  }
-  return bound;
-}
-
-// Export pagination types
-export type { PaginatedResponse, PaginationMetadata } from "./interfaces/IPaginatedResponse";

package/src/interfaces/IPaginatedResponse.ts

@@ -1,12 +0,0 @@
-export interface PaginationMetadata {
-  page: number;
-  pageSize: number;
-  totalPages: number;
-  totalItems: number;
-  hasMore: boolean;
-}
-
-export interface PaginatedResponse<T> {
-  data: T[];
-  pagination: PaginationMetadata;
-}

package/src/modules/comments/fetchComment.ts

@@ -1,14 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface FetchCommentProps {
-  commentId: string;
-}
-
-export async function fetchComment(
-  client: SublayHttpClient,
-  data: FetchCommentProps
-): Promise<any> {
-  const path = `/comments/${data.commentId}`;
-  const response = await client.instance.get<any>(path);
-  return response.data;
-}

package/src/modules/comments/fetchCommentByForeignId.ts

@@ -1,14 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface FetchCommentByForeignIdProps {
-  foreignId: string;
-}
-
-export async function fetchCommentByForeignId(
-  client: SublayHttpClient,
-  data: FetchCommentByForeignIdProps
-): Promise<any> {
-  const path = `/comments/by-foreign-id`;
-  const response = await client.instance.get<any>(path, { params: data });
-  return response.data;
-}

package/src/modules/comments/index.ts

@@ -1,4 +0,0 @@
-import { fetchComment } from "./fetchComment";
-import { fetchCommentByForeignId } from "./fetchCommentByForeignId";
-
-export { fetchComment, fetchCommentByForeignId };

package/src/modules/entities/createEntity.ts

@@ -1,27 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export 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;
-}
-
-// TODO: Replace "any" with Entity once we have types here too
-export async function createEntity(
-  client: SublayHttpClient,
-  data: CreateEntityProps
-): Promise<any> {
-  const path = `/entities`; // assuming client handles prefix like /{projectId}
-  const response = await client.instance.post<any>(path, data);
-  return response.data;
-}

package/src/modules/entities/deleteEntity.ts

@@ -1,14 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface DeleteEntityProps {
-  entityId: string;
-}
-
-export async function deleteEntity(
-  client: SublayHttpClient,
-  data: DeleteEntityProps
-): Promise<any> {
-  const path = `/entities/${data.entityId}`;
-  const response = await client.instance.delete<any>(path);
-  return response.data;
-}

package/src/modules/entities/fetchEntity.ts

@@ -1,14 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface FetchEntityProps {
-  entityId: string;
-}
-
-export async function fetchEntity(
-  client: SublayHttpClient,
-  data: FetchEntityProps
-): Promise<any> {
-  const path = `/entities/${data.entityId}`;
-  const response = await client.instance.get<any>(path);
-  return response.data;
-}

package/src/modules/entities/fetchEntityByForeignId.ts

@@ -1,15 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface FetchEntityByForeignIdProps {
-  foreignId: string;
-  createIfNotFound?: boolean;
-}
-
-export async function fetchEntityByForeignId(
-  client: SublayHttpClient,
-  data: FetchEntityByForeignIdProps
-): Promise<any> {
-  const path = `/entities/by-foreign-id`;
-  const response = await client.instance.get<any>(path, { params: data });
-  return response.data;
-}

package/src/modules/entities/fetchEntityByShortId.ts

@@ -1,14 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface FetchEntityByShortIdProps {
-  shortId: string;
-}
-
-export async function fetchEntityByShortId(
-  client: SublayHttpClient,
-  data: FetchEntityByShortIdProps
-): Promise<any> {
-  const path = `/entities/by-short-id`;
-  const response = await client.instance.get<any>(path, { params: data });
-  return response.data;
-}

package/src/modules/entities/fetchManyEntities.ts

@@ -1,79 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-import { PaginatedResponse } from "../../interfaces/IPaginatedResponse";
-
-export interface KeywordsFilters {
-  includes?: string[];
-  doesNotInclude?: string[];
-}
-
-export interface MetadataFilters {
-  includes?: { [key: string]: any };
-  doesNotInclude?: { [key: string]: any };
-  exists?: string[];
-  doesNotExist?: string[];
-}
-
-export interface TextFilters {
-  hasTitle?: "true" | "false";
-  includes?: string | string[];
-  doesNotInclude?: string | string[];
-}
-
-export interface AttachmentsFilters {
-  hasAttachments?: "true" | "false";
-}
-
-export interface LocationFilters {
-  latitude: string;
-  longitude: string;
-  radius: string;
-}
-
-export interface FetchManyEntitiesProps {
-  sourceId?: string;
-  spaceId?: string;
-
-  // Sorting & Pagination
-  sortBy?: "hot" | "top" | "controversial";
-  page?: number;
-  limit?: number;
-
-  // Time-based filtering
-  timeFrame?: "hour" | "day" | "week" | "month" | "year";
-
-  userId?: string;
-  followedOnly?: "true";
-
-  // Keyword filters
-  keywordsFilters?: KeywordsFilters;
-
-  // Metadata filters
-  metadataFilters?: MetadataFilters;
-
-  // Title filtering
-  titleFilters?: TextFilters;
-
-  // Content filtering
-  contentFilters?: {
-    hasContent?: "true" | "false";
-    includes?: string | string[];
-    doesNotInclude?: string | string[];
-  };
-
-  // Media filtering
-  attachmentsFilters?: AttachmentsFilters;
-
-  // Location filtering
-  locationFilters?: LocationFilters;
-}
-
-export async function fetchManyEntities(
-  client: SublayHttpClient,
-  data: FetchManyEntitiesProps
-): Promise<PaginatedResponse<any>> {
-  const path = `/entities`;
-  const response = await client.instance.get<PaginatedResponse<any>>(path, {
-    params: data,
-  });
-  return response.data;
-}

package/src/modules/entities/index.ts

@@ -1,17 +0,0 @@
-import { createEntity } from "./createEntity";
-import { fetchEntity } from "./fetchEntity";
-import { fetchEntityByForeignId } from "./fetchEntityByForeignId";
-import { fetchEntityByShortId } from "./fetchEntityByShortId";
-import { fetchManyEntities } from "./fetchManyEntities";
-import { updateEntity } from "./updateEntity";
-import { deleteEntity } from "./deleteEntity";
-
-export {
-  createEntity,
-  fetchEntity,
-  fetchEntityByForeignId,
-  fetchEntityByShortId,
-  fetchManyEntities,
-  updateEntity,
-  deleteEntity,
-};

package/src/modules/entities/updateEntity.ts

@@ -1,28 +0,0 @@
-import { SublayHttpClient } from "../../core/client";
-
-export interface UpdateEntityProps {
-  entityId: string;
-  title?: string;
-  content?: string;
-  attachments?: Record<string, any>[];
-  keywords?: string[];
-  location?: {
-    type: "Point";
-    coordinates: [number, number]; // [longitude, latitude]
-  };
-  metadata?: Record<string, any>;
-  mentions?: {
-    id: string;
-    username: string;
-  }[];
-}
-
-export async function updateEntity(
-  client: SublayHttpClient,
-  data: UpdateEntityProps
-): Promise<any> {
-  const { entityId, ...restOfProps } = data;
-  const path = `/entities/${data.entityId}`;
-  const response = await client.instance.patch<any>(path, restOfProps);
-  return response.data;
-}