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 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
- # 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
+ [![Docs](https://img.shields.io/badge/docs-docs.bulkit.io-blue)](https://docs.bulkit.io/docs?utm_source=npm&utm_medium=readme&utm_campaign=node_sdk)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./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)