Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,16 @@ earlier history lives in git log only.

## [Unreleased]

## [4.185.0] - 2026-11-21

### Added

- **`bulk(items, { createOnly: true })`**, sent as `create_only`: every item with an id is created as `create` creates it, never replaced. An id the world already holds answers that item's slot `409` `id_conflict`, and the element stays as it was; the rest of the batch goes on as before. Left out or false, the body is the one earlier releases sent. A value that is not `true` or `false` is refused before anything is sent.

### Changed

- `me()`'s comment says a PIN beside a key that cannot write is never read by onlyworlds.com (since 21 November 2026), so the call tests a PIN only for a key that can write.

## [4.184.1] - 2026-11-21

### Changed
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@onlyworlds/sdk",
"version": "4.184.1",
"version": "4.185.0",
"description": "TypeScript SDK for the OnlyWorlds API - build world-building applications with type safety",
"type": "module",
"exports": {
Expand Down
19 changes: 15 additions & 4 deletions src/v2/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,8 @@ export class OwV2Client {
* membership and Character, the lenses it starts with, the world's reading aids, and the front
* door (`front_door`: the sponsor and their Character, your own Character, the Charter and the
* Objects it names, the seats you sponsor). The client's PIN is sent here when it has one, so a
* wrong PIN shows on this call first, which makes it the connection test. An account token is
* wrong PIN shows on this call first, which makes it the connection test for a key that can write;
* beside a key that cannot (a read key, a player's), onlyworlds.com never reads a PIN. An account token is
* refused before sending: it is not a member of one world.
*/
async me(): Promise<OwMe> {
Expand Down Expand Up @@ -456,9 +457,18 @@ export class OwV2Client {
* `idempotencyKey`, derived from the key and the position (the ids the Python package mints),
* so a retry with the same key and items sends the same body; without one, a
* fresh UUIDv7. Ids you supply are kept.
*/
async bulk(items: OwBulkItem[], opts: { atomic?: boolean; idempotencyKey?: string } = {}): Promise<OwBulkResponse> {
only('bulk', opts, ['atomic', 'idempotencyKey']);
* With `createOnly: true` (sent as `create_only`), every item with an id is created as `create` creates it, never
* replaced: an id the world already holds answers that item's slot `{status: 409}` with `id_conflict`, and the
* element stays as it was. Left out or false, an item with an id held replaces it whole, as before.
*/
async bulk(
items: OwBulkItem[],
opts: { atomic?: boolean; idempotencyKey?: string; createOnly?: boolean } = {},
): Promise<OwBulkResponse> {
only('bulk', opts, ['atomic', 'idempotencyKey', 'createOnly']);
if (opts.createOnly !== undefined && typeof opts.createOnly !== 'boolean') {
throw new TypeError('bulk: createOnly is true or false. Nothing was sent.');
}
// A stub anywhere refuses the whole call before sending (never a skipped slot:
// the response's slots line up with `items`).
items.forEach((it, index) => refuseKnownOf(it.element, `bulk: items[${index}]`));
Expand All @@ -471,6 +481,7 @@ export class OwV2Client {
return { type: it.type, element };
}),
atomic: opts.atomic ?? false,
...(opts.createOnly === true ? { create_only: true } : {}),
};
return this.request('POST', '/bulk/', {
write: true,
Expand Down
17 changes: 17 additions & 0 deletions test/v2-client.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,23 @@ test('bulk atomic:true is forwarded', async () => {
assert.equal(lastBody(fetchImpl).atomic, true);
});

test('bulk createOnly:true is sent as create_only; left out or false, the body is as before', async () => {
const { client, fetchImpl } = makeClient({ status: 200, body: FIX_P2a });
const items = [{ type: 'character', element: { id: 'mine', name: 'A' } }];
await client.bulk(items, { createOnly: true });
assert.deepEqual(Object.keys(lastBody(fetchImpl)), ['items', 'atomic', 'create_only']);
assert.equal(lastBody(fetchImpl).create_only, true);
for (const opts of [{}, { createOnly: false }]) {
await client.bulk(items, opts);
assert.deepEqual(Object.keys(lastBody(fetchImpl)), ['items', 'atomic'], JSON.stringify(opts));
}
const before = fetchImpl.calls.length;
for (const bad of ['true', 1, null]) {
await assert.rejects(client.bulk(items, { createOnly: bad }), (err) => err instanceof TypeError && /createOnly is true or false/.test(err.message));
}
assert.equal(fetchImpl.calls.length, before, 'a refused createOnly sends nothing');
});

// -- bulk response parse against literal P2a / P2c bodies -------------------

test('bulk parses P2a success body (items[], numeric status, timestamp echo)', async () => {
Expand Down