post-upload 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ ## 1.2.0 — 2026-11-22
4
+
5
+ The package is renamed from `indreelforge` to **`post-upload`** (the product's new name). The `indreelforge` npm package is deprecated; this release is backward compatible with it.
6
+
7
+ ### Changed
8
+ - npm package name `post-upload`; main class `PostUpload` (also the default export) and error class `PostUploadError`. `IndReelForge`, `InReelForge`, `IndReelForgeError` and `InReelForgeError` remain as deprecated aliases of the same classes. `err.name` is now `'PostUploadError'`.
9
+ - Default API address `https://api.post-upload.com`, MCP endpoint `https://api.post-upload.com/mcp`.
10
+ - CLI is `post-upload` (`npx -y post-upload mcp`), reading `POST_UPLOAD_API_KEY`, `POST_UPLOAD_MCP_URL` and `POST_UPLOAD_MCP_TIMEOUT_MS`, with the `INDREELFORGE_*` names as a fallback. An `indreelforge` bin is still installed.
11
+ - User-Agent is `post-upload-node/<version>`.
12
+
13
+ ### Added
14
+ - Chunked uploads for videos up to 500 MB. `uploadVideo` sends local files and Buffers over 95 MiB (`CHUNKED_THRESHOLD_BYTES`) through `/api/upload/chunked/*` automatically (or always/never with `chunked: true | false`), reading the file one part at a time, retrying parts on 429 / 5xx / network errors with backoff and `Retry-After`, cancelling the session on failure, and reporting `onProgress`.
15
+ - `uploadLargeFile(source, options)` and the low-level `createUploadSession`, `uploadPart`, `completeUploadSession`, `getUploadSession` and `abortUploadSession`.
16
+ - `uploadVideo` accepts `stagedFileId`, a Buffer / stream as `video`, and the source as the first argument: `uploadVideo('./v.mp4', { user, platforms })`.
17
+ - `new PostUpload('api-key')` shorthand.
18
+ - Six platforms (22 in total): `devto`, `hashnode`, `lemmy`, `nostr`, `whop`, `listmonk`, in `Platform`, `PLATFORMS`, `PlatformCredentials` and `CREDENTIAL_PLATFORMS`.
19
+ - `data.skipped_platforms` (`SkippedPlatform[]`) and `data.error_message` in `UploadResponse`; `error_code` on `UploadWarning` (`platform_skipped`).
20
+ - `PostUploadError.retryAfter` (seconds from the `Retry-After` header).
21
+
22
+ ## 1.1.0 (not published to npm)
23
+
24
+ - Typed methods for the full REST API, typed errors (`IndReelForgeError`), `npx indreelforge mcp` stdio bridge, Discord, Telegram, Slack, Mastodon and WordPress with `connectWithCredentials`.
25
+
26
+ ## 1.0.1 / 1.0.0
27
+
28
+ - First releases on npm as `indreelforge`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 IndReelForge
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,526 @@
1
- # Temporary Holding Version
1
+ # Post-Upload — Node.js SDK & MCP bridge
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/post-upload.svg)](https://www.npmjs.com/package/post-upload)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
+
6
+ Official Node.js SDK for the [Post-Upload](https://post-upload.com) Social Media API. Publish videos, photos, text and documents to **22 platforms** with a single API call: **Instagram, YouTube, TikTok, Facebook, X (Twitter), LinkedIn, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop & Listmonk**.
7
+
8
+ Videos up to **500 MB** are supported: files over 95 MiB are sent automatically in parts through the chunked upload API.
9
+
10
+ The package also ships `npx post-upload mcp`, a zero-dependency stdio bridge that connects AI agents (Claude Desktop, Cursor and other MCP clients) to the hosted Post-Upload MCP server.
11
+
12
+ > **Renamed from `indreelforge`.** This package was published on npm as [`indreelforge`](https://www.npmjs.com/package/indreelforge), which is deprecated and gets no further updates. Switch with `npm uninstall indreelforge && npm install post-upload` and change your imports from `'indreelforge'` to `'post-upload'`. The old class names (`IndReelForge`, `InReelForge`, `IndReelForgeError`, `InReelForgeError`) are still exported as deprecated aliases of `PostUpload` / `PostUploadError`, and the `INDREELFORGE_*` environment variables are still read by the CLI, so nothing else has to change. See [Migrating from `indreelforge`](#migrating-from-indreelforge).
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install post-upload
18
+ ```
19
+
20
+ Requires Node.js 18 or newer (uses the built-in `fetch`, `FormData` and `Blob`). No runtime dependencies.
21
+
22
+ ## Quick start
23
+
24
+ ```typescript
25
+ import PostUpload from 'post-upload';
26
+
27
+ const client = new PostUpload(process.env.POST_UPLOAD_API_KEY!);
28
+
29
+ const result = await client.uploadVideo('./my-video.mp4', {
30
+ user: 'my-profile',
31
+ platforms: ['instagram', 'tiktok', 'youtube'],
32
+ title: 'Check out this video!',
33
+ });
34
+
35
+ console.log(result.data.upload_id);
36
+ ```
37
+
38
+ CommonJS works too: `const { PostUpload } = require('post-upload');`
39
+
40
+ ## Configuration
41
+
42
+ ```typescript
43
+ const client = new PostUpload({
44
+ apiKey: 'your-api-key', // Required. Dashboard → API Keys
45
+ baseUrl: 'https://api.post-upload.com', // Optional (default)
46
+ timeout: 120000, // Optional, ms (default 120 s; chunk uploads get at least 300 s)
47
+ fetch: customFetch, // Optional, custom fetch implementation
48
+ headers: { 'X-Trace': 'abc' }, // Optional, extra headers on every request
49
+ retryBaseDelayMs: 1000, // Optional, first retry delay for chunked-upload steps
50
+ });
51
+
52
+ // Or just the key (plus optional options):
53
+ const client2 = new PostUpload('your-api-key', { timeout: 60000 });
54
+ ```
55
+
56
+ Every request sends `Authorization: Apikey <key>` and `User-Agent: post-upload-node/<version>`.
57
+
58
+ ## Publishing
59
+
60
+ ### Common upload options
61
+
62
+ All `upload*` methods accept:
63
+
64
+ | Option | API field | Description |
65
+ |---|---|---|
66
+ | `user` | `user` | Profile name (required) |
67
+ | `platforms` | `platform[]` | `instagram`, `youtube`, `tiktok`, `facebook`, `x`, `linkedin`, `threads`, `pinterest`, `reddit`, `bluesky`, `google_business`, `discord`, `telegram`, `slack`, `mastodon`, `wordpress`, `devto`, `hashnode`, `lemmy`, `nostr`, `whop`, `listmonk` (also exported as `PLATFORMS`) |
68
+ | `title` | `title` | Title / caption |
69
+ | `description` | `description` | Long description |
70
+ | `firstComment` | `first_comment` | First comment |
71
+ | `schedule` | `schedule` | ISO-8601 datetime to publish later |
72
+ | `timezone` | `timezone` | IANA timezone for `schedule` |
73
+ | `addToQueue` | `add_to_queue` | Put the post in the profile's next free queue slot |
74
+ | `asyncUpload` | `async_upload` | `false` = wait (up to ~50 s) for the publish result |
75
+ | `requestId` | `request_id` | Your own correlation id (see `getRequestStatus`) |
76
+ | `idempotencyKey` | `Idempotency-Key` header | Retries with the same key never double-post |
77
+ | `platformOptions` | any | Platform-specific fields, sent as-is (see below) |
78
+
79
+ ### Upload a video
80
+
81
+ ```typescript
82
+ // From a local file (path as the first argument, or `videoPath` in the options)
83
+ await client.uploadVideo('./video.mp4', {
84
+ user: 'my-profile',
85
+ platforms: ['instagram', 'tiktok', 'youtube', 'facebook'],
86
+ title: 'My video',
87
+ firstComment: '#socialmedia',
88
+ schedule: '2026-12-01T10:00:00Z',
89
+ youtubePrivacy: 'public',
90
+ youtubeTags: ['tutorial', 'tech'],
91
+ idempotencyKey: 'video-2026-12-01',
92
+ });
93
+
94
+ // From a public URL (up to 500 MB; the server downloads it)
95
+ await client.uploadVideo({
96
+ user: 'my-profile',
97
+ platforms: ['tiktok'],
98
+ videoUrl: 'https://cdn.example.com/clip.mp4',
99
+ });
100
+
101
+ // From a Buffer or a readable stream
102
+ await client.uploadVideo(buffer, { user: 'my-profile', platforms: ['youtube'], filename: 'clip.mp4' });
103
+ ```
104
+
105
+ ### Large videos (chunked upload, up to 500 MB)
106
+
107
+ Requests to the API are capped at 100 MB at the edge. `uploadVideo` sends any local file or Buffer larger than **95 MiB** (`CHUNKED_THRESHOLD_BYTES`) through the [chunked upload endpoints](https://docs.post-upload.com/api-reference/upload-video#large-files-chunked-upload) automatically: it opens an upload session, sends the file in parts (each exactly the server's `chunk_size`, 32 MiB, read from disk one part at a time), completes the session and publishes it by `staged_file_id`. Parts are sent one after another and retried with exponential backoff on `429`, `5xx` and network errors (honouring `Retry-After`); if a part fails for good the session is cancelled.
108
+
109
+ ```typescript
110
+ await client.uploadVideo('./full-episode.mp4', {
111
+ user: 'my-profile',
112
+ platforms: ['youtube', 'facebook'],
113
+ title: 'Full episode',
114
+ onProgress: ({ uploadedBytes, totalBytes, part, totalParts }) =>
115
+ console.log(`part ${part}/${totalParts}: ${Math.round((uploadedBytes / totalBytes) * 100)}%`),
116
+ });
117
+ ```
118
+
119
+ | Option | Description |
120
+ |---|---|
121
+ | `chunked` | `'auto'` (default: above 95 MiB), `true` (always) or `false` (never) |
122
+ | `onProgress` | Called after each part with `{ uploadedBytes, totalBytes, part, totalParts }` |
123
+ | `maxRetries` | Attempts per part / step on 429, 5xx and network errors (default 5) |
124
+ | `filename`, `mimeType` | For a Buffer or stream (default `video.mp4`; the type is guessed from the name) |
125
+ | `size` | Size in bytes of a stream. With `size` a stream is read part by part; without it, a `chunked: true` stream is first written to a temporary file (deleted afterwards). In `'auto'` mode a stream without `size` is sent in a single request |
126
+
127
+ Send the file now and post it later, or drive the steps yourself:
128
+
129
+ ```typescript
130
+ // Upload only, then post by staged_file_id (usable once, within 6 hours)
131
+ const { staged_file_id } = await client.uploadLargeFile('./full-episode.mp4', { onProgress });
132
+ await client.uploadVideo({ user: 'my-profile', platforms: ['youtube'], stagedFileId: staged_file_id });
133
+
134
+ // Low-level
135
+ const session = await client.createUploadSession({ filename: 'a.mp4', size, mime_type: 'video/mp4' });
136
+ // → { upload_session_id, chunk_size, total_chunks, expires_at }
137
+ await client.uploadPart(session.upload_session_id, 0, firstChunkBytes); // one attempt per call
138
+ await client.getUploadSession(session.upload_session_id); // received_chunks, to resume
139
+ const done = await client.completeUploadSession(session.upload_session_id); // → { staged_file_id }
140
+ await client.abortUploadSession(session.upload_session_id); // cancel
141
+ ```
142
+
143
+ ### Skipped platforms
144
+
145
+ Each platform has its own maximum file size (e.g. Instagram 300 MB, Bluesky 100 MB, Discord 10 MB). A platform the file is too large for is skipped while the others publish. Skipped platforms are listed in `data.skipped_platforms` (typed as `SkippedPlatform[]`) and as `platform_skipped` entries in `warnings`:
146
+
147
+ ```typescript
148
+ const res = await client.uploadVideo('./big.mp4', { user: 'my-profile', platforms: ['youtube', 'bluesky'] });
149
+ for (const s of res.data.skipped_platforms ?? []) {
150
+ console.warn(`${s.platform} skipped: ${s.message} (${s.file_size_mb} MB > ${s.max_size_mb} MB)`);
151
+ }
152
+ ```
153
+
154
+ Only when no selected platform can take the file is the request refused (`413 FILE_TOO_LARGE_FOR_PLATFORM`).
155
+
156
+ ### Upload photos
157
+
158
+ Local files, public URLs, or both — up to 10 in total.
159
+
160
+ ```typescript
161
+ await client.uploadPhotos({
162
+ user: 'my-profile',
163
+ platforms: ['instagram', 'facebook', 'pinterest'],
164
+ photoPaths: ['./photo1.jpg'],
165
+ photoUrls: ['https://cdn.example.com/photo2.jpg'],
166
+ title: 'Photo carousel',
167
+ platformOptions: { pinterest_board_id: '1234567890' },
168
+ });
169
+ ```
170
+
171
+ ### Text post
172
+
173
+ ```typescript
174
+ await client.uploadText({
175
+ user: 'my-profile',
176
+ platforms: ['x', 'threads', 'bluesky', 'linkedin', 'devto', 'nostr'],
177
+ text: 'Just shipped a new feature!', // `title` is still accepted as before
178
+ });
179
+ ```
180
+
181
+ ### Document post (LinkedIn)
182
+
183
+ ```typescript
184
+ await client.uploadDocument({
185
+ user: 'my-profile',
186
+ documentPath: './deck.pdf', // PDF, PPT, PPTX, DOC, DOCX (max 100 MB)
187
+ title: 'Q4 results',
188
+ visibility: 'PUBLIC',
189
+ targetLinkedinPageId: '12345', // optional: post as a company page
190
+ });
191
+ ```
192
+
193
+ ### Synchronous mode
194
+
195
+ By default an upload returns immediately and publishes in the background. With `asyncUpload: false` the server waits up to about 50 seconds and returns the outcome:
196
+
197
+ ```typescript
198
+ const res = await client.uploadText({ user: 'my-profile', platforms: ['bluesky'], text: 'hi', asyncUpload: false });
199
+ if (res.sync) {
200
+ console.log(res.data.status, res.data.platforms, res.data.platform_post_ids);
201
+ } else {
202
+ // Took longer than the wait window: poll instead
203
+ console.log(await client.getUploadStatus(res.data.upload_id));
204
+ }
205
+ ```
206
+
207
+ ### Platform-specific options
208
+
209
+ Pass any platform-specific API field through `platformOptions`. Arrays are sent as repeated fields, booleans as `"true"`/`"false"`, objects as JSON.
210
+
211
+ ```typescript
212
+ await client.uploadPhotos({
213
+ user: 'my-profile',
214
+ platforms: ['tiktok', 'google_business', 'reddit'],
215
+ photoUrls: ['https://cdn.example.com/menu.jpg'],
216
+ title: 'New menu is live',
217
+ platformOptions: {
218
+ privacy_level: 'PUBLIC_TO_EVERYONE', // TikTok
219
+ auto_add_music: true,
220
+ gbp_location_id: 'locations/123', // Google Business Profile
221
+ gbp_cta_type: 'LEARN_MORE',
222
+ gbp_cta_url: 'https://example.com',
223
+ reddit_subreddit: 'food', // Reddit
224
+ },
225
+ });
226
+ ```
227
+
228
+ Use the platform helper methods below to look up page, board and location ids. The full list of platform fields is in the [platform guides](https://docs.post-upload.com).
229
+
230
+ **Per-platform text overrides (every platform).** `<platform>_title` and `<platform>_description` replace the shared `title` / `description` for that platform only, e.g. `x_title`, `linkedin_description`, `mastodon_title`, `devto_description`.
231
+
232
+ **Mastodon**
233
+
234
+ | Field | Values |
235
+ |---|---|
236
+ | `mastodon_visibility` | `public` (default), `unlisted`, `private` or `direct` |
237
+ | `mastodon_spoiler_text` | Content warning shown before the post |
238
+ | `mastodon_sensitive` | `true` to mark media as sensitive. Omit it otherwise: the server treats any non-empty value, including `"false"`, as true |
239
+ | `mastodon_alt_text` | Alt text for attached media (defaults to the title) |
240
+ | `mastodon_language` | ISO 639 language code, e.g. `en` |
241
+
242
+ **WordPress**
243
+
244
+ | Field | Values |
245
+ |---|---|
246
+ | `wordpress_status` | `publish` (default) or `draft` |
247
+ | `wordpress_categories` | Numeric category IDs: `'3,7'` or `[3, 7]` |
248
+ | `wordpress_tags` | Numeric tag IDs: `'12,15'` or `[12, 15]` |
249
+
250
+ ```typescript
251
+ await client.uploadText({
252
+ user: 'my-profile',
253
+ platforms: ['mastodon', 'wordpress', 'slack'],
254
+ title: 'Release notes',
255
+ description: 'Full changelog for 1.2 …',
256
+ platformOptions: {
257
+ mastodon_title: 'Release notes are out (short version for Mastodon)',
258
+ mastodon_visibility: 'unlisted',
259
+ mastodon_language: 'en',
260
+ wordpress_status: 'draft',
261
+ wordpress_categories: [3, 7],
262
+ wordpress_tags: '12,15',
263
+ },
264
+ });
265
+ ```
266
+
267
+ ## Connect platforms with credentials
268
+
269
+ Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop and Listmonk connect with credentials instead of an OAuth login. `connectWithCredentials(profile, platform, credentials)` sends them to the API, which verifies them live with the platform before saving them (encrypted). Connecting again replaces the stored credentials. The credentials object is typed per platform:
270
+
271
+ | Platform | Credentials (`?` = optional) |
272
+ |---|---|
273
+ | `discord` | `{ webhook_url }` — channel webhook URL |
274
+ | `telegram` | `{ bot_token, chat_id }` — token from @BotFather; public channel `@username` or numeric chat ID |
275
+ | `slack` | `{ webhook_url }` — incoming webhook URL (Slack can only verify it on the first post) |
276
+ | `mastodon` | `{ instance_url, access_token }` — e.g. `https://mastodon.social`; token with `write:statuses` and `write:media` |
277
+ | `wordpress` | `{ site_url, username, app_password }` — self-hosted site, a user who can publish, an application password |
278
+ | `devto` | `{ api_key, base_url? }` — DEV API key (Settings → Extensions); `base_url` only for another Forem site |
279
+ | `hashnode` | `{ access_token, publication_id }` — personal access token; the publication must be on Hashnode Pro |
280
+ | `lemmy` | `{ instance_url, username, password, community, totp? }` — `community` is `name` or `name@instance`; `totp` only with 2FA (used once, not stored) |
281
+ | `nostr` | `{ nsec, relays?, blossom_server? }` — `nsec1…` or hex key; comma-separated `wss://` relays; Blossom server for photos |
282
+ | `whop` | `{ api_key, experience_id?, channel_id? }` — a forum `experience_id` (exp_…) or a chat `channel_id`, not both |
283
+ | `listmonk` | `{ base_url, api_user, api_token, list_ids }` — Listmonk URL, an API user and token, comma-separated list IDs |
284
+
285
+ ```typescript
286
+ const res = await client.connectWithCredentials('my-profile', 'telegram', {
287
+ bot_token: '123456789:AA…',
288
+ chat_id: '@mychannel',
289
+ });
290
+ console.log(res.platform_username);
291
+
292
+ await client.connectWithCredentials('my-profile', 'devto', { api_key: process.env.DEVTO_API_KEY! });
293
+
294
+ try {
295
+ await client.connectWithCredentials('my-profile', 'mastodon', { instance_url: 'https://mastodon.social', access_token: 'bad' });
296
+ } catch (err) {
297
+ if (err instanceof PostUploadError && err.status === 400) {
298
+ // err.code: 'MISSING_FIELD' | 'FIELD_TOO_LONG' | 'INVALID_CREDENTIALS'
299
+ console.error(err.code, err.body?.details?.field, err.message);
300
+ }
301
+ }
302
+ ```
303
+
304
+ Other failures: `404` (profile not found) and `502` (the platform could not be reached to verify the details). The required fields per platform are also exported as `CREDENTIAL_PLATFORMS`.
305
+
306
+ ## All methods
307
+
308
+ | Area | Method | Endpoint |
309
+ |---|---|---|
310
+ | Upload | `uploadVideo(options)` / `uploadVideo(source, options)` | `POST /api/upload` (plus the chunked endpoints for large files) |
311
+ | | `uploadPhotos(options)` | `POST /api/upload_photos` |
312
+ | | `uploadText(options)` | `POST /api/upload_text` |
313
+ | | `uploadDocument(options)` | `POST /api/upload_document` |
314
+ | Chunked upload | `uploadLargeFile(source, { filename, mimeType, size, onProgress, maxRetries })` | init → parts → complete |
315
+ | | `createUploadSession({ filename, size, mime_type })` | `POST /api/upload/chunked/init` |
316
+ | | `uploadPart(sessionId, index, bytes)` | `PUT /api/upload/chunked/:id/:index` |
317
+ | | `completeUploadSession(sessionId)` | `POST /api/upload/chunked/:id/complete` |
318
+ | | `getUploadSession(sessionId)` | `GET /api/upload/chunked/:id` |
319
+ | | `abortUploadSession(sessionId)` | `DELETE /api/upload/chunked/:id` |
320
+ | Account | `getMe()` | `GET /api/me` |
321
+ | Uploads | `getUploadStatus(uploadId)` | `GET /api/upload/:id/status` |
322
+ | | `getRequestStatus(requestId)` | `GET /api/uploadposts/status?request_id=` |
323
+ | | `listUploads({ limit, page, status })` | `GET /api/uploads` |
324
+ | | `getUpload(uploadId)` | `GET /api/uploads/:id` |
325
+ | | `deleteUpload(uploadId)` | `DELETE /api/uploads/:id` |
326
+ | | `retryUpload(uploadId)` | `POST /api/uploads/:id/retry` |
327
+ | | `getPlatformLimits()` | `GET /api/platform-limits` |
328
+ | Profiles | `getProfiles()` | `GET /api/profiles` |
329
+ | | `createProfile(name)` | `POST /api/profiles` |
330
+ | | `deleteProfile(name)` | `DELETE /api/profiles/:name` |
331
+ | | `connectWithCredentials(profile, platform, credentials)` | `POST /api/profiles/:name/connect/:platform/credentials` |
332
+ | Schedule | `getScheduledPosts()` | `GET /api/schedule` |
333
+ | | `updateScheduledPost(jobId, { scheduledDate, timezone, title, caption })` | `PATCH /api/schedule/:jobId` |
334
+ | | `cancelScheduledPost(jobId)` | `DELETE /api/schedule/:jobId` |
335
+ | Queue | `getQueueSettings(profile)` | `GET /api/queue/settings` |
336
+ | | `updateQueueSettings({ profile, slots, daysOfWeek, timezone, maxPostsPerSlot })` | `POST /api/queue/settings` |
337
+ | | `getQueuePreview(profile, count?)` | `GET /api/queue/preview` |
338
+ | | `getNextQueueSlot(profile)` | `GET /api/queue/next-slot` |
339
+ | Platform helpers | `getFacebookPages(profile)` | `GET /api/platforms/facebook/pages` |
340
+ | | `getLinkedInPages(profile)` | `GET /api/platforms/linkedin/pages` |
341
+ | | `getPinterestBoards(profile)` | `GET /api/platforms/pinterest/boards` |
342
+ | | `getGoogleBusinessLocations(profile)` | `GET /api/platforms/google-business/locations` |
343
+ | Analytics | `getAnalytics(range = '30d')` | `GET /api/analytics/overview` |
344
+ | | `getLiveAnalytics(profile, platforms?)` | `GET /api/analytics/live/:profile` |
345
+ | | `getPostAnalytics(uploadId, platform?)` | `GET /api/analytics/post/:upload_id` |
346
+ | | `getTotalImpressions(profile, { platform, period, startDate, endDate })` | `GET /api/analytics/total-impressions/:profile` |
347
+ | FFmpeg | `getFfmpegUsage()` | `GET /api/ffmpeg/usage` |
348
+ | | `listFfmpegJobs()` | `GET /api/ffmpeg/jobs` |
349
+ | | `getFfmpegJob(jobId)` | `GET /api/ffmpeg/jobs/:jobId` |
350
+ | Plans | `getPlans()` | `GET /api/plans` |
351
+
352
+ Examples:
353
+
354
+ ```typescript
355
+ const me = await client.getMe(); // plan + monthly usage
356
+ const { uploads } = await client.listUploads({ status: 'failed', limit: 10 });
357
+ await client.retryUpload(uploads[0].id);
358
+
359
+ await client.updateQueueSettings({
360
+ profile: 'my-profile',
361
+ slots: ['09:00', '17:30'],
362
+ daysOfWeek: [1, 2, 3, 4, 5],
363
+ timezone: 'Europe/London',
364
+ });
365
+ await client.uploadVideo('./v.mp4', { user: 'my-profile', platforms: ['youtube'], addToQueue: true });
366
+
367
+ const { scheduled_posts } = await client.getScheduledPosts();
368
+ await client.updateScheduledPost(scheduled_posts[0].id, { scheduledDate: '2026-12-24T09:00:00Z' });
369
+ ```
370
+
371
+ ## Error handling
372
+
373
+ Every API failure throws a `PostUploadError`:
374
+
375
+ | Property | Description |
376
+ |---|---|
377
+ | `status` | HTTP status (`0` = network error, `408` = client-side timeout) |
378
+ | `code` | API error code (`error_code` / `code`), e.g. `MISSING_VIDEO`, `CHUNK_SIZE_MISMATCH`, or `NETWORK_ERROR` / `TIMEOUT` |
379
+ | `body` | Parsed response body |
380
+ | `message` | Human-readable message from the API |
381
+ | `retryAfter` | Seconds from the `Retry-After` header (e.g. on 429), or `null` |
382
+
383
+ ```typescript
384
+ import { PostUploadError } from 'post-upload';
385
+
386
+ try {
387
+ await client.uploadVideo('./v.mp4', { user: 'my-profile', platforms: ['tiktok'] });
388
+ } catch (err) {
389
+ if (err instanceof PostUploadError) {
390
+ console.error(`API error ${err.status} (${err.code}): ${err.message}`, err.body);
391
+ } else {
392
+ throw err;
393
+ }
394
+ }
395
+ ```
396
+
397
+ Invalid arguments (for example no video source, or more than 10 photos) throw a `TypeError` before any request is made.
398
+
399
+ ## MCP: use Post-Upload from AI agents
400
+
401
+ Post-Upload runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server, so Claude, ChatGPT, Cursor and other agents can publish posts, check upload status and read analytics with your API key.
402
+
403
+ ### Option 1 — stdio bridge (Claude Desktop, Cursor, any stdio MCP client)
404
+
405
+ Add this to your client's MCP config (`claude_desktop_config.json` for Claude Desktop; `~/.cursor/mcp.json` or `.cursor/mcp.json` for Cursor):
406
+
407
+ ```json
408
+ {
409
+ "mcpServers": {
410
+ "post-upload": {
411
+ "command": "npx",
412
+ "args": ["-y", "post-upload", "mcp"],
413
+ "env": {
414
+ "POST_UPLOAD_API_KEY": "your-api-key"
415
+ }
416
+ }
417
+ }
418
+ }
419
+ ```
420
+
421
+ Environment variables:
422
+
423
+ | Variable | Required | Description |
424
+ |---|---|---|
425
+ | `POST_UPLOAD_API_KEY` | yes | Your Post-Upload API key |
426
+ | `POST_UPLOAD_MCP_URL` | no | MCP endpoint (default `https://api.post-upload.com/mcp`) |
427
+ | `POST_UPLOAD_MCP_TIMEOUT_MS` | no | Per-request timeout in ms (default `300000`) |
428
+
429
+ The former `INDREELFORGE_API_KEY`, `INDREELFORGE_MCP_URL` and `INDREELFORGE_MCP_TIMEOUT_MS` are still read when the new names are not set.
430
+
431
+ The bridge reads JSON-RPC messages from stdin, forwards each to the hosted server and writes the responses to stdout, one per line. Only JSON-RPC goes to stdout; diagnostics go to stderr. HTTP and network failures come back as JSON-RPC errors for the matching request id, so the client never hangs. `npx post-upload --help` and `npx post-upload --version` are available.
432
+
433
+ ### Option 2 — connect to the hosted URL directly
434
+
435
+ Clients that support remote (Streamable HTTP) MCP servers with custom headers (for example Cursor or Claude Code) can skip the bridge:
436
+
437
+ - URL: `https://api.post-upload.com/mcp`
438
+ - Header: `Authorization: ApiKey your-api-key`
439
+
440
+ ```json
441
+ {
442
+ "mcpServers": {
443
+ "post-upload": {
444
+ "url": "https://api.post-upload.com/mcp",
445
+ "headers": { "Authorization": "ApiKey your-api-key" }
446
+ }
447
+ }
448
+ }
449
+ ```
450
+
451
+ Claude Code:
452
+
453
+ ```bash
454
+ claude mcp add --transport http post-upload https://api.post-upload.com/mcp \
455
+ --header "Authorization: ApiKey your-api-key"
456
+ ```
457
+
458
+ ### Programmatic bridge
459
+
460
+ ```typescript
461
+ import { runMcpBridge } from 'post-upload';
462
+
463
+ await runMcpBridge({ apiKey: process.env.POST_UPLOAD_API_KEY!, input: process.stdin, output: process.stdout });
464
+ ```
465
+
466
+ ## Supported platforms
467
+
468
+ | Platform | Video | Photo | Text | Document | Scheduling |
469
+ |----------|-------|-------|------|----------|------------|
470
+ | Instagram | ✓ | ✓ | - | - | ✓ |
471
+ | YouTube | ✓ | - | - | - | ✓ |
472
+ | TikTok | ✓ | ✓ | - | - | ✓ |
473
+ | Facebook | ✓ | ✓ | ✓ | - | ✓ |
474
+ | X (Twitter) | ✓ | ✓ | ✓ | - | ✓ |
475
+ | LinkedIn | ✓ | ✓ | ✓ | ✓ | ✓ |
476
+ | Threads | ✓ | ✓ | ✓ | - | ✓ |
477
+ | Pinterest | ✓ | ✓ | - | - | ✓ |
478
+ | Reddit | ✓ | ✓ | ✓ | - | ✓ |
479
+ | Bluesky | ✓ | ✓ | ✓ | - | ✓ |
480
+ | Google Business Profile | - | ✓ | ✓ | - | ✓ |
481
+ | Discord | ✓ | ✓ | ✓ | - | ✓ |
482
+ | Telegram | ✓ | ✓ | ✓ | - | ✓ |
483
+ | Slack | - | - | ✓ | - | ✓ |
484
+ | Mastodon | ✓ | ✓ | ✓ | - | ✓ |
485
+ | WordPress | ✓ | ✓ | ✓ | - | ✓ |
486
+ | Dev.to | - | - | ✓ | - | ✓ |
487
+ | Hashnode | - | ✓ | ✓ | - | ✓ |
488
+ | Lemmy | - | ✓ | ✓ | - | ✓ |
489
+ | Nostr | - | ✓ | ✓ | - | ✓ |
490
+ | Whop | ✓ | ✓ | ✓ | - | ✓ |
491
+ | Listmonk | - | ✓ | ✓ | - | ✓ |
492
+
493
+ Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop and Listmonk are connected with [credentials](#connect-platforms-with-credentials); the others connect through an OAuth login in the dashboard (or an app password for Bluesky).
494
+
495
+ ## Migrating from `indreelforge`
496
+
497
+ 1.2 is backward compatible with the `indreelforge` 1.0 / 1.1 API; only the package name changed.
498
+
499
+ ```bash
500
+ npm uninstall indreelforge
501
+ npm install post-upload
502
+ ```
503
+
504
+ ```diff
505
+ - import IndReelForge, { IndReelForgeError } from 'indreelforge';
506
+ - const client = new IndReelForge({ apiKey: process.env.INDREELFORGE_API_KEY! });
507
+ + import PostUpload, { PostUploadError } from 'post-upload';
508
+ + const client = new PostUpload({ apiKey: process.env.POST_UPLOAD_API_KEY! });
509
+ ```
510
+
511
+ - `IndReelForge` / `InReelForge` and `IndReelForgeError` / `InReelForgeError` are still exported as deprecated aliases of the same classes, so existing code and `instanceof` checks keep working. `err.name` is now `'PostUploadError'`; prefer `instanceof` checks.
512
+ - The default API address is now `https://api.post-upload.com` (the old `api.indreelforge.com` address keeps working while it is phased out). Pass `baseUrl` to override.
513
+ - The CLI is `post-upload` (`npx -y post-upload mcp`); an `indreelforge` bin is still installed, and the `INDREELFORGE_*` environment variables are still read.
514
+ - New: chunked uploads up to 500 MB, `uploadVideo(source, options)`, `new PostUpload('key')`, six new platforms and `skipped_platforms` in upload responses. See [CHANGELOG.md](CHANGELOG.md).
515
+
516
+ ## Links
517
+
518
+ - [Website](https://post-upload.com)
519
+ - [API documentation](https://docs.post-upload.com)
520
+ - [Dashboard](https://post-upload.com/dashboard)
521
+ - [Pricing](https://post-upload.com/pricing)
522
+ - [Python SDK](https://pypi.org/project/post-upload/)
523
+
524
+ ## License
525
+
526
+ MIT