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 +28 -0
- package/LICENSE +21 -0
- package/README.md +525 -2
- package/dist/cli.js +297 -0
- package/dist/index.d.mts +660 -0
- package/dist/index.d.ts +660 -0
- package/dist/index.js +1034 -0
- package/dist/index.mjs +984 -0
- package/package.json +96 -4
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
|
-
#
|
|
1
|
+
# Post-Upload — Node.js SDK & MCP bridge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/post-upload)
|
|
4
|
+
[](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
|