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 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
- # bulkit
1
+ # Bulkit Node.js SDK
2
2
 
3
- Placeholder package. This name is reserved for an upcoming release. Stay tuned.
3
+ [![npm](https://img.shields.io/npm/v/bulkit.svg)](https://www.npmjs.com/package/bulkit)
4
+ [![CI](https://github.com/bulkit-io/bulkit/actions/workflows/ci.yml/badge.svg)](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)