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