schedulifyx-sdk 1.0.0

package/README.md

@@ -0,0 +1,242 @@
+# @schedulifyx/sdk
+
+Official JavaScript/TypeScript SDK for [SchedulifyX API](https://schedulifyx.com/docs) - Social media scheduling made easy.
+
+## Installation
+
+```bash
+npm install @schedulifyx/sdk
+# or
+yarn add @schedulifyx/sdk
+# or
+pnpm add @schedulifyx/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Schedulify } from '@schedulifyx/sdk';
+
+const client = new Schedulify('sk_live_YOUR_API_KEY');
+
+// List all posts
+const posts = await client.posts.list();
+console.log(posts.data);
+
+// Create a scheduled post
+const post = await client.posts.create({
+  content: 'Hello from the SDK! 🚀',
+  accountIds: ['acc_123'],
+  publishAt: '2024-12-20T10:00:00Z'
+});
+
+// Publish immediately
+await client.posts.publish(post.data.id);
+```
+
+## Configuration
+
+```typescript
+import { Schedulify } from '@schedulify/sdk';
+
+// Simple initialization
+const client = new Schedulify('sk_live_YOUR_API_KEY');
+
+// With options
+const client = new Schedulify({
+  apiKey: 'sk_live_YOUR_API_KEY',
+  baseUrl: 'https://api.schedulifyx.com', // optional
+  timeout: 30000 // optional, in ms
+});
+```
+
+## API Reference
+
+### Posts
+
+```typescript
+// List posts with filters
+const posts = await client.posts.list({
+  status: 'scheduled',
+  accountId: 'acc_123',
+  limit: 20,
+  offset: 0
+});
+
+// Get single post
+const post = await client.posts.get('post_123');
+
+// Create post
+const newPost = await client.posts.create({
+  content: 'Hello world!',
+  accountIds: ['acc_123', 'acc_456'],
+  publishAt: '2024-12-20T10:00:00Z',
+  mediaUrls: ['https://example.com/image.jpg'],
+  platformOverrides: {
+    twitter: { content: 'Hello Twitter! #launch' }
+  }
+});
+
+// Update post
+await client.posts.update('post_123', {
+  content: 'Updated content',
+  publishAt: '2024-12-21T10:00:00Z'
+});
+
+// Delete post
+await client.posts.delete('post_123');
+
+// Publish immediately
+await client.posts.publish('post_123');
+```
+
+### Accounts
+
+```typescript
+// List all connected accounts
+const accounts = await client.accounts.list();
+
+// Filter by platform
+const instagramAccounts = await client.accounts.list({
+  platform: 'instagram'
+});
+
+// Get single account
+const account = await client.accounts.get('acc_123');
+
+// Get Pinterest boards
+const boards = await client.accounts.getPinterestBoards('acc_pinterest_123');
+```
+
+### Media Upload
+
+```typescript
+// Get presigned upload URL
+const { data } = await client.media.getUploadUrl({
+  filename: 'my-image.jpg',
+  contentType: 'image/jpeg'
+});
+
+// Upload using the presigned URL
+await fetch(data.uploadUrl, {
+  method: 'PUT',
+  headers: { 'Content-Type': 'image/jpeg' },
+  body: imageBuffer
+});
+
+// Use mediaUrl in your post
+await client.posts.create({
+  content: 'Check out this image!',
+  accountIds: ['acc_123'],
+  mediaUrls: [data.mediaUrl]
+});
+
+// Or use the convenience helper (Node.js)
+const mediaUrl = await client.media.upload(imageBuffer, 'image.jpg', 'image/jpeg');
+```
+
+### Analytics
+
+```typescript
+// Get overview
+const overview = await client.analytics.overview();
+
+// Get account-specific analytics
+const accountAnalytics = await client.analytics.forAccount('acc_123', {
+  days: 30
+});
+
+// Get all analytics
+const allAnalytics = await client.analytics.list({
+  startDate: '2024-01-01',
+  endDate: '2024-12-31'
+});
+```
+
+### Queue
+
+```typescript
+// Get queue schedule
+const queue = await client.queue.getSlots('profile_123');
+
+// Set queue schedule
+await client.queue.setSlots({
+  profileId: 'profile_123',
+  timezone: 'America/New_York',
+  slots: [
+    { dayOfWeek: 1, time: '09:00' },
+    { dayOfWeek: 1, time: '15:00' },
+    { dayOfWeek: 2, time: '09:00' }
+  ],
+  active: true
+});
+
+// Get next available slot
+const nextSlot = await client.queue.getNextSlot('profile_123');
+
+// Preview upcoming slots
+const preview = await client.queue.preview('profile_123', 10);
+```
+
+### Usage
+
+```typescript
+const usage = await client.usage();
+console.log(`${usage.data.requestsToday}/${usage.data.dailyLimit} daily requests used`);
+```
+
+### Multi-Tenant (Enterprise)
+
+```typescript
+// Create a tenant
+const tenant = await client.tenants.create({
+  externalId: 'user_123',
+  email: 'user@example.com',
+  name: 'John Doe'
+});
+
+// Get OAuth URL for tenant
+const { data } = await client.tenants.getConnectUrl(tenant.data.id, 'instagram');
+// Redirect user to data.url
+
+// List tenant's accounts
+const accounts = await client.tenants.listAccounts(tenant.data.id);
+
+// Disconnect account
+await client.tenants.disconnectAccount(tenant.data.id, 'acc_123');
+```
+
+## Error Handling
+
+```typescript
+import { Schedulify, SchedulifyError } from '@schedulify/sdk';
+
+try {
+  await client.posts.create({...});
+} catch (error) {
+  if (error instanceof SchedulifyError) {
+    console.error('API Error:', error.code, error.message);
+    console.error('Status:', error.status);
+    console.error('Details:', error.details);
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type { 
+  Post, 
+  Account, 
+  Analytics, 
+  Tenant, 
+  QueueSchedule,
+  SchedulifyConfig 
+} from '@schedulifyx/sdk';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,363 @@
+/**
+ * SchedulifyX SDK - Official JavaScript/TypeScript SDK
+ * https://schedulifyx.com/docs
+ */
+interface SchedulifyConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface Post {
+    id: string;
+    content: string;
+    mediaUrls?: string[];
+    status: 'draft' | 'scheduled' | 'publishing' | 'published' | 'failed';
+    publishAt?: string;
+    publishNow?: boolean;
+    accountIds: string[];
+    platformOverrides?: Record<string, {
+        content?: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Account {
+    id: string;
+    platform: string;
+    platformAccountId: string;
+    name: string;
+    username?: string;
+    profilePicture?: string;
+    isActive: boolean;
+    createdAt: string;
+}
+interface Analytics {
+    accountId: string;
+    followers: number;
+    following: number;
+    posts: number;
+    engagement: number;
+    updatedAt: string;
+}
+interface AnalyticsOverview {
+    totalPosts: number;
+    scheduledPosts: number;
+    publishedPosts: number;
+    failedPosts: number;
+    totalAccounts: number;
+    activeAccounts: number;
+}
+interface Usage {
+    requestsToday: number;
+    dailyLimit: number;
+    remainingToday: number;
+    monthlyRequests: number;
+    lastUsedAt: string | null;
+}
+interface Tenant {
+    id: string;
+    externalId: string;
+    email?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+interface QueueSlot {
+    dayOfWeek: number;
+    time: string;
+}
+interface QueueSchedule {
+    id: string;
+    profileId: string;
+    timezone: string;
+    slots: QueueSlot[];
+    active: boolean;
+}
+interface MediaUploadResponse {
+    uploadUrl: string;
+    mediaUrl: string;
+    expiresIn: number;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+interface ApiError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+declare class SchedulifyError extends Error {
+    code: string;
+    status: number;
+    details?: Record<string, unknown>;
+    constructor(message: string, code: string, status: number, details?: Record<string, unknown>);
+}
+declare class Schedulify {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: SchedulifyConfig | string);
+    private request;
+    posts: {
+        /**
+         * List all posts with optional filters
+         */
+        list: (params?: {
+            status?: "draft" | "scheduled" | "publishing" | "published" | "failed";
+            accountId?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<PaginatedResponse<Post>>;
+        /**
+         * Get a single post by ID
+         */
+        get: (postId: string) => Promise<{
+            data: Post;
+        }>;
+        /**
+         * Create a new post
+         */
+        create: (data: {
+            content: string;
+            accountIds: string[];
+            publishAt?: string;
+            publishNow?: boolean;
+            mediaUrls?: string[];
+            platformOverrides?: Record<string, {
+                content?: string;
+            }>;
+        }) => Promise<{
+            data: Post;
+        }>;
+        /**
+         * Update an existing post
+         */
+        update: (postId: string, data: {
+            content?: string;
+            publishAt?: string;
+            mediaUrls?: string[];
+        }) => Promise<{
+            data: Post;
+        }>;
+        /**
+         * Delete a post
+         */
+        delete: (postId: string) => Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Publish a post immediately
+         */
+        publish: (postId: string) => Promise<{
+            data: Post;
+        }>;
+    };
+    accounts: {
+        /**
+         * List all connected social accounts
+         */
+        list: (params?: {
+            platform?: string;
+            limit?: number;
+            offset?: number;
+        }) => Promise<PaginatedResponse<Account>>;
+        /**
+         * Get a single account by ID
+         */
+        get: (accountId: string) => Promise<{
+            data: Account;
+        }>;
+        /**
+         * Get Pinterest boards for a Pinterest account
+         */
+        getPinterestBoards: (accountId: string) => Promise<{
+            data: {
+                id: string;
+                name: string;
+            }[];
+        }>;
+    };
+    analytics: {
+        /**
+         * Get analytics overview
+         */
+        overview: () => Promise<{
+            data: AnalyticsOverview;
+        }>;
+        /**
+         * Get analytics for a specific account
+         */
+        forAccount: (accountId: string, params?: {
+            days?: number;
+        }) => Promise<{
+            data: Analytics[];
+        }>;
+        /**
+         * Get all analytics data
+         */
+        list: (params?: {
+            accountId?: string;
+            startDate?: string;
+            endDate?: string;
+        }) => Promise<{
+            data: Analytics[];
+        }>;
+    };
+    media: {
+        /**
+         * Get a presigned URL for uploading media
+         */
+        getUploadUrl: (data: {
+            filename: string;
+            contentType: string;
+        }) => Promise<{
+            data: MediaUploadResponse;
+        }>;
+        /**
+         * Helper to upload a file and return the media URL
+         */
+        upload: (file: Blob | Buffer, filename: string, contentType: string) => Promise<string>;
+    };
+    /**
+     * Get API usage statistics
+     */
+    usage: () => Promise<{
+        data: Usage;
+    }>;
+    queue: {
+        /**
+         * Get queue schedule for a profile
+         */
+        getSlots: (profileId: string) => Promise<{
+            data: {
+                exists: boolean;
+                schedule?: QueueSchedule;
+                nextSlots?: string[];
+            };
+        }>;
+        /**
+         * Create or update queue schedule
+         */
+        setSlots: (data: {
+            profileId: string;
+            timezone: string;
+            slots: QueueSlot[];
+            active?: boolean;
+            reshuffleExisting?: boolean;
+        }) => Promise<{
+            data: QueueSchedule;
+        }>;
+        /**
+         * Delete queue schedule
+         */
+        deleteSlots: (profileId: string) => Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Get the next available slot
+         */
+        getNextSlot: (profileId: string) => Promise<{
+            data: {
+                nextSlot: string;
+                timezone: string;
+            };
+        }>;
+        /**
+         * Preview upcoming slots
+         */
+        preview: (profileId: string, count?: number) => Promise<{
+            data: {
+                slots: string[];
+            };
+        }>;
+    };
+    tenants: {
+        /**
+         * List all tenants
+         */
+        list: (params?: {
+            limit?: number;
+            offset?: number;
+            search?: string;
+        }) => Promise<PaginatedResponse<Tenant>>;
+        /**
+         * Get a single tenant
+         */
+        get: (tenantId: string) => Promise<{
+            data: Tenant;
+        }>;
+        /**
+         * Create a new tenant
+         */
+        create: (data: {
+            externalId: string;
+            email?: string;
+            name?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<{
+            data: Tenant;
+        }>;
+        /**
+         * Update a tenant
+         */
+        update: (tenantId: string, data: {
+            email?: string;
+            name?: string;
+            metadata?: Record<string, unknown>;
+        }) => Promise<{
+            data: Tenant;
+        }>;
+        /**
+         * Delete a tenant
+         */
+        delete: (tenantId: string) => Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Get OAuth URL for tenant to connect a platform
+         */
+        getConnectUrl: (tenantId: string, platform: string) => Promise<{
+            data: {
+                url: string;
+            };
+        }>;
+        /**
+         * List tenant's connected accounts
+         */
+        listAccounts: (tenantId: string) => Promise<{
+            data: Account[];
+        }>;
+        /**
+         * Disconnect a tenant's account
+         */
+        disconnectAccount: (tenantId: string, accountId: string) => Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Connect Bluesky account for tenant
+         */
+        connectBluesky: (tenantId: string, data: {
+            identifier: string;
+            appPassword: string;
+        }) => Promise<{
+            data: Account;
+        }>;
+        /**
+         * Connect Mastodon account for tenant
+         */
+        connectMastodon: (tenantId: string, data: {
+            instance: string;
+            accessToken: string;
+        }) => Promise<{
+            data: Account;
+        }>;
+    };
+}
+
+export { type Account, type Analytics, type AnalyticsOverview, type ApiError, type MediaUploadResponse, type PaginatedResponse, type Post, type QueueSchedule, type QueueSlot, Schedulify, type SchedulifyConfig, SchedulifyError, type Tenant, type Usage, Schedulify as default };