diff --git a/CHANGELOG.md b/CHANGELOG.md index afa3a02..9e94fd6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/package-lock.json b/package-lock.json index f05ccc9..e9a7bcc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@onlyworlds/sdk", - "version": "4.184.1", + "version": "4.185.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@onlyworlds/sdk", - "version": "4.184.1", + "version": "4.185.0", "license": "MIT", "dependencies": { "fflate": "^0.8.3" diff --git a/package.json b/package.json index 6bd4f5b..194707b 100644 --- a/package.json +++ b/package.json @@ -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": { diff --git a/src/v2/client.ts b/src/v2/client.ts index e453be3..f6b6465 100644 --- a/src/v2/client.ts +++ b/src/v2/client.ts @@ -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 { @@ -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 { - 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 { + 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}]`)); @@ -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, diff --git a/test/v2-client.test.mjs b/test/v2-client.test.mjs index 1aedb5f..9422634 100644 --- a/test/v2-client.test.mjs +++ b/test/v2-client.test.mjs @@ -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 () => {