bulkit 0.0.1 → 0.1.1
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/LICENSE +21 -0
- package/README.md +266 -2
- package/dist/index.cjs +853 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +5741 -0
- package/dist/index.d.ts +5741 -0
- package/dist/index.js +828 -0
- package/dist/index.js.map +1 -0
- package/package.json +86 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Bulkit
|
|
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,267 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Bulkit Node.js SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/bulkit)
|
|
4
|
+
[](https://docs.bulkit.io/docs?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
**Schedule and publish to X, LinkedIn, Instagram, Facebook, Threads, TikTok, YouTube, Pinterest,
|
|
8
|
+
Reddit, Bluesky and Vimeo from your own code.**
|
|
9
|
+
|
|
10
|
+
[Bulkit](https://bulkit.io?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk) is a social
|
|
11
|
+
media scheduler built for developers and AI agents. Write a post once, tailor it per network,
|
|
12
|
+
and Bulkit handles each platform's limits, media rules, threads and retries. This package is the
|
|
13
|
+
official TypeScript / JavaScript client for its API.
|
|
14
|
+
|
|
15
|
+
**[Start your 14-day free trial →](https://app.bulkit.io/register?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)**
|
|
16
|
+
· [Get an API key](#get-your-api-key) ·
|
|
17
|
+
[Documentation](https://docs.bulkit.io/docs?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)
|
|
18
|
+
|
|
19
|
+
- One call posts to many networks, with a different text for each one
|
|
20
|
+
- Threads, images and video, scheduling, comments, and webhooks
|
|
21
|
+
- Fully typed, generated from the Bulkit OpenAPI spec
|
|
22
|
+
- Zero runtime dependencies, ESM and CommonJS
|
|
23
|
+
- Retries with backoff, timeouts, and automatic idempotency keys on every write
|
|
24
|
+
|
|
25
|
+
## Get your API key
|
|
26
|
+
|
|
27
|
+
You need a Bulkit account and an API key before the SDK can do anything. It takes a few minutes:
|
|
28
|
+
|
|
29
|
+
1. **Create an account.** [Sign up for Bulkit](https://app.bulkit.io/register?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk).
|
|
30
|
+
Every plan starts with a 14-day free trial.
|
|
31
|
+
2. **Connect your social accounts.** Bulkit publishes through your own platform apps (your X
|
|
32
|
+
app, your LinkedIn app, and so on). Add them and connect your accounts in the app. The
|
|
33
|
+
[workspace setup guide](https://docs.bulkit.io/docs/setup?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)
|
|
34
|
+
walks you through each network.
|
|
35
|
+
3. **Create a key.** In the app, open **Developers → API & Webhooks** and click **Create key**.
|
|
36
|
+
Copy it straight away, because it is only shown once.
|
|
37
|
+
|
|
38
|
+
Put the key in an environment variable, never in your code:
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
# .env
|
|
42
|
+
BULKIT_API_KEY=bk_test_xxxxxxxxxxxxxxxx
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
> **Start with a test key.** A `bk_test_…` key checks and saves your requests exactly like a
|
|
46
|
+
> live key, but never publishes to a real account and is never billed. Switch to a `bk_live_…`
|
|
47
|
+
> key when you are ready to go live. See [Create an API key](https://docs.bulkit.io/docs/api-keys?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)
|
|
48
|
+
> for details.
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
npm install bulkit
|
|
54
|
+
# or: pnpm add bulkit / yarn add bulkit / bun add bulkit
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Requires Node.js 22 or later. Other runtimes with `fetch` and Web Crypto (Bun, Deno, Cloudflare
|
|
58
|
+
Workers) should also work.
|
|
59
|
+
|
|
60
|
+
## Usage
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import { Bulkit } from 'bulkit';
|
|
64
|
+
|
|
65
|
+
const bulkit = new Bulkit({
|
|
66
|
+
apiKey: process.env.BULKIT_API_KEY, // this is the default and can be omitted
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
// 1. What can I post to, and what will each platform accept?
|
|
70
|
+
const channels = await bulkit.channels.list();
|
|
71
|
+
const platforms = await bulkit.platforms.list();
|
|
72
|
+
|
|
73
|
+
// 2. Schedule one submission to several channels.
|
|
74
|
+
const post = await bulkit.posts.create({
|
|
75
|
+
intent: 'schedule',
|
|
76
|
+
scheduledAt: '2026-11-01T09:00:00Z',
|
|
77
|
+
channels: [
|
|
78
|
+
{ channelId: 'chn_x', blocks: [{ content: 'Shipping today.' }] },
|
|
79
|
+
{ channelId: 'chn_li', blocks: [{ content: 'A longer version, for LinkedIn.' }] },
|
|
80
|
+
],
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
console.log(post.id, post.status); // "scheduled"
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
> Call `posts.create` **once** with several entries in `channels`. Calling it once per channel
|
|
87
|
+
> creates several unrelated submissions, each with its own id and schedule.
|
|
88
|
+
|
|
89
|
+
### Test mode
|
|
90
|
+
|
|
91
|
+
A `bk_test_…` key validates and stores exactly like a live key, but publishes nothing and bills
|
|
92
|
+
nothing. `bulkit.isTestMode` tells you which kind of key a client holds.
|
|
93
|
+
|
|
94
|
+
## Publishing is asynchronous
|
|
95
|
+
|
|
96
|
+
`intent: 'now'` and `posts.publish()` return as soon as the work is queued, with status
|
|
97
|
+
`publishing`. That does not mean the post is live. Each channel publishes on its own, so a
|
|
98
|
+
submission can end up `partially_published`. Find out what happened through
|
|
99
|
+
[webhooks](#webhooks) (preferred) or by calling `posts.retrieve(id)`.
|
|
100
|
+
|
|
101
|
+
## Pagination
|
|
102
|
+
|
|
103
|
+
List methods return a page you can `await`, or iterate directly to get every item across every
|
|
104
|
+
page:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
for await (const post of bulkit.posts.list({ status: ['failed'] })) {
|
|
108
|
+
await bulkit.posts.publish(post.id); // retries; already-published channels are skipped
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
// Or page by hand:
|
|
112
|
+
let page = await bulkit.posts.list({ limit: 50 });
|
|
113
|
+
while (page.hasNextPage()) {
|
|
114
|
+
page = await page.getNextPage();
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Media
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { openAsBlob } from 'node:fs';
|
|
122
|
+
|
|
123
|
+
const image = await bulkit.media.upload(await openAsBlob('photo.jpg', { type: 'image/jpeg' }), {
|
|
124
|
+
fileName: 'photo.jpg',
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
// Large video goes through a resumable upload session; the SDK handles the parts.
|
|
128
|
+
const video = await bulkit.media.uploadMultipart(await openAsBlob('launch.mp4'), {
|
|
129
|
+
fileName: 'launch.mp4',
|
|
130
|
+
mimeType: 'video/mp4',
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Webhooks
|
|
135
|
+
|
|
136
|
+
Verify every delivery against the **raw** request body. Re-serialized JSON will not match the
|
|
137
|
+
signature.
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
import express from 'express';
|
|
141
|
+
import { verifyWebhook, WebhookVerificationError } from 'bulkit';
|
|
142
|
+
|
|
143
|
+
app.post('/webhooks/bulkit', express.raw({ type: 'application/json' }), async (req, res) => {
|
|
144
|
+
try {
|
|
145
|
+
const event = await verifyWebhook(req.body, req.headers, {
|
|
146
|
+
secret: process.env.BULKIT_WEBHOOK_SECRET!,
|
|
147
|
+
});
|
|
148
|
+
if (event.type === 'post.failed') {
|
|
149
|
+
console.log(event.data.channelId, event.data.error);
|
|
150
|
+
}
|
|
151
|
+
res.sendStatus(200);
|
|
152
|
+
} catch (err) {
|
|
153
|
+
res.sendStatus(err instanceof WebhookVerificationError ? 400 : 500);
|
|
154
|
+
}
|
|
155
|
+
});
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Delivery is at-least-once, so dedupe on `event.id`. Test a receiver with
|
|
159
|
+
`bulkit.webhooks.test(endpointId)`, which works with test keys too.
|
|
160
|
+
|
|
161
|
+
## Error handling
|
|
162
|
+
|
|
163
|
+
Every API failure throws a subclass of `APIError`. Branch on `code` rather than `message`:
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
import { APIError, QuotaExceededError, RateLimitError } from 'bulkit';
|
|
167
|
+
|
|
168
|
+
try {
|
|
169
|
+
await bulkit.posts.create(params);
|
|
170
|
+
} catch (err) {
|
|
171
|
+
if (err instanceof QuotaExceededError) {
|
|
172
|
+
// The plan's allowance is spent. Retrying will not help; see bulkit.usage.retrieve().
|
|
173
|
+
} else if (err instanceof APIError) {
|
|
174
|
+
console.error(err.status, err.code, err.field, err.requestId);
|
|
175
|
+
} else {
|
|
176
|
+
throw err;
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
| Status | Error |
|
|
182
|
+
| ------ | -------------------------------------------------- |
|
|
183
|
+
| 400 | `BadRequestError` |
|
|
184
|
+
| 401 | `AuthenticationError` |
|
|
185
|
+
| 402 | `QuotaExceededError` |
|
|
186
|
+
| 403 | `PermissionDeniedError` |
|
|
187
|
+
| 404 | `NotFoundError` |
|
|
188
|
+
| 409 | `ConflictError` |
|
|
189
|
+
| 413 | `PayloadTooLargeError` |
|
|
190
|
+
| 415 | `UnsupportedMediaTypeError` |
|
|
191
|
+
| 422 | `UnprocessableEntityError` |
|
|
192
|
+
| 429 | `RateLimitError` |
|
|
193
|
+
| 5xx | `InternalServerError` |
|
|
194
|
+
| none | `APIConnectionError` / `APIConnectionTimeoutError` |
|
|
195
|
+
|
|
196
|
+
All of them extend `BulkitError`.
|
|
197
|
+
|
|
198
|
+
## Retries and idempotency
|
|
199
|
+
|
|
200
|
+
Every `POST` and `PUT` is sent with an `Idempotency-Key`. The SDK generates one per call and
|
|
201
|
+
reuses it across its own retries, so a retried write can never publish twice. Pass your own
|
|
202
|
+
key to keep retries safe across process restarts:
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
await bulkit.posts.create(params, { idempotencyKey: `campaign-${campaignId}` });
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
These failures are retried twice by default, with exponential backoff that honours
|
|
209
|
+
`Retry-After`:
|
|
210
|
+
- connection errors and timeouts
|
|
211
|
+
- `408`, `429`, `502`, `503` and `504`
|
|
212
|
+
- `409 request_in_progress`
|
|
213
|
+
- `500`, on reads only
|
|
214
|
+
|
|
215
|
+
A `500` on a write is not retried, because the API replays the same failure for the same key.
|
|
216
|
+
`402` and other `4xx` errors are never retried.
|
|
217
|
+
|
|
218
|
+
```ts
|
|
219
|
+
const bulkit = new Bulkit({ maxRetries: 5, timeout: 20_000 }); // client-wide
|
|
220
|
+
await bulkit.posts.list({}, { maxRetries: 0, signal: AbortSignal.timeout(5_000) }); // per call
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Response metadata
|
|
224
|
+
|
|
225
|
+
```ts
|
|
226
|
+
const { data, requestId, rateLimit, response } = await bulkit.channels.list().withResponse();
|
|
227
|
+
console.log(rateLimit.remaining, requestId);
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Include the `requestId` (also on every `APIError`) when you contact support.
|
|
231
|
+
|
|
232
|
+
## Configuration
|
|
233
|
+
|
|
234
|
+
| Option | Default |
|
|
235
|
+
| ------------------------- | ----------------------------------------------------------- |
|
|
236
|
+
| `apiKey` | `process.env.BULKIT_API_KEY` |
|
|
237
|
+
| `baseURL` | `process.env.BULKIT_BASE_URL`, then `https://api.bulkit.io` |
|
|
238
|
+
| `timeout` | `60000` ms per attempt |
|
|
239
|
+
| `maxRetries` | `2` |
|
|
240
|
+
| `defaultHeaders` | `{}` |
|
|
241
|
+
| `fetch` | `globalThis.fetch` |
|
|
242
|
+
| `dangerouslyAllowBrowser` | `false` |
|
|
243
|
+
|
|
244
|
+
Your API key is a secret. The client refuses to run in a browser unless you opt in with
|
|
245
|
+
`dangerouslyAllowBrowser`.
|
|
246
|
+
|
|
247
|
+
## Versioning
|
|
248
|
+
|
|
249
|
+
This package follows [SemVer](https://semver.org). The API version (`/public/v1`) is fixed per
|
|
250
|
+
major version of the SDK.
|
|
251
|
+
|
|
252
|
+
## Learn more
|
|
253
|
+
|
|
254
|
+
- [Bulkit documentation](https://docs.bulkit.io/docs?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk): guides, platform rules and the full API reference
|
|
255
|
+
- [Connect an AI agent (MCP)](https://docs.bulkit.io/docs/guides/mcp?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk): let Claude, Cursor and other agents post through Bulkit
|
|
256
|
+
- [Supported networks](https://bulkit.io/channels?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)
|
|
257
|
+
- Questions? Email [support@bulkit.io](mailto:support@bulkit.io) or find us on [X](https://x.com/bulkitio)
|
|
258
|
+
|
|
259
|
+
**New to Bulkit? [Start your 14-day free trial →](https://app.bulkit.io/register?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)**
|
|
260
|
+
|
|
261
|
+
## Contributing
|
|
262
|
+
|
|
263
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
264
|
+
|
|
265
|
+
## License
|
|
266
|
+
|
|
267
|
+
[MIT](./LICENSE)
|