@cocreate/api 2.0.0 → 2.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/CHANGELOG.md CHANGED
@@ -1,3 +1,26 @@
1
+ ## [2.1.1](https://github.com/CoCreateJS/api/compare/v2.1.0...v2.1.1) (2026-11-07)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * complete unified socket package migration ([3dc2f13](https://github.com/CoCreateJS/api/commit/3dc2f136b9745b4f1b95b65bc477a611ec91c8e0))
7
+ * preserve socket data in API responses ([0668a04](https://github.com/CoCreateJS/api/commit/0668a0477ef1332b2debb374ca175b471dc94503))
8
+ * route API replies through server send ([a092f17](https://github.com/CoCreateJS/api/commit/a092f17cb3cd39a2c9bb05a07175d375b7aae162))
9
+ * route component responses through unified server send ([7bc2168](https://github.com/CoCreateJS/api/commit/7bc2168d79a36eced19bc5d2447e11bab37113a4))
10
+
11
+ # [2.1.0](https://github.com/CoCreateJS/api/compare/v2.0.0...v2.1.0) (2026-11-05)
12
+
13
+
14
+ ### Bug Fixes
15
+
16
+ * support authorized manager operation dispatch ([a899876](https://github.com/CoCreateJS/api/commit/a8998763dfd213d4ba64663a3ce294dd117729b8))
17
+ * upgrade CoCreate dependencies to v2 ([4a3a3af](https://github.com/CoCreateJS/api/commit/4a3a3afe4675c977625c9567472dc5fc26820637))
18
+
19
+
20
+ ### Features
21
+
22
+ * add authorized API HTTP request handling ([42894e6](https://github.com/CoCreateJS/api/commit/42894e69525388e6e021758f3d7ffb4f1e4ad687))
23
+
1
24
  # [2.0.0](https://github.com/CoCreateJS/api/compare/v1.23.2...v2.0.0) (2026-11-02)
2
25
 
3
26
 
package/README.md CHANGED
@@ -359,4 +359,9 @@ https://cocreatejs.com/docs/api
359
359
  This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
360
360
 
361
361
  - **Open Source Use:** For open-source projects and non-commercial use, this software is available under the AGPLv3. For the full license text, see the LICENSE file.
362
- - **Commercial Use:** Commercial users must obtain a commercial license. Commercial licenses are available when signing up for an API key through the CoCreate platform.
362
+ - **Commercial Use:** Commercial users must obtain a commercial license. Commercial licenses are available when signing up for an API key through the CoCreate platform.
363
+ ## HTTP entrance
364
+
365
+ The initialized API service exposes `http(req, res)` alongside `webhook(req, res)`. The module accepts POST JSON bodies up to 1 MiB, resolves organization scope from the hostname, and authorizes through `server.authorize.request` before execution. Bearer API keys and the envelope `apikey` field are supported; conflicting keys are rejected. Missing permission or authorization service returns 403. Caller scope and socket/user identity are excluded, and execution uses the sanitized envelope without the transport key.
366
+
367
+ `send()` remains the execution API used by trusted internal calls and socket dispatch, where socket authorization already occurs. The existing webhook AST owns provider signature verification.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cocreate/api",
3
- "version": "2.0.0",
3
+ "version": "2.1.1",
4
4
  "description": "A secure, multi-tenant API execution gateway and proxy layer that dynamically resolves endpoint actions, processes AST micro-operators, handles webhooks, and manages third-party integrations with strict tenant environment isolation.",
5
5
  "keywords": [
6
6
  "api-orchestration",
@@ -51,14 +51,14 @@
51
51
  }
52
52
  },
53
53
  "dependencies": {
54
- "@cocreate/actions": "^1.24.0",
55
- "@cocreate/crud-client": "^1.37.0",
56
- "@cocreate/element-prototype": "^1.35.0",
57
- "@cocreate/render": "^1.51.0",
58
- "@cocreate/socket-client": "^1.43.0",
59
- "@cocreate/utils": "^1.54.0"
54
+ "@cocreate/actions": "^2.0.0",
55
+ "@cocreate/crud-client": "^2.0.0",
56
+ "@cocreate/element-prototype": "^2.0.0",
57
+ "@cocreate/render": "^2.0.0",
58
+ "@cocreate/utils": "^2.0.0",
59
+ "@cocreate/socket": "^2.0.1"
60
60
  },
61
61
  "devDependencies": {
62
- "@cocreate/webpack": "^1.9.0"
62
+ "@cocreate/webpack": "^2.0.0"
63
63
  }
64
64
  }
package/src/client.js CHANGED
@@ -1,7 +1,7 @@
1
1
  /*globals CustomEvent, config*/
2
2
  import { getValueFromObject, dotNotationToObject } from "@cocreate/utils";
3
3
  import Observer from "@cocreate/observer";
4
- import Socket from "@cocreate/socket-client";
4
+ import { SocketClient as Socket } from "@cocreate/socket";
5
5
  import Actions from "@cocreate/actions";
6
6
  import { render } from "@cocreate/render";
7
7
  import "@cocreate/element-prototype";
@@ -402,8 +402,7 @@ export default CoCreateApi;
402
402
  * Declares/registers an API provider name; provider-specific attributes are derived from this name.
403
403
  *
404
404
  * @name api | module
405
- * @kind member
406
- * @attribute
405
+ * @kind attribute
407
406
  * @valueType string
408
407
  * @environment client
409
408
  */
@@ -412,8 +411,7 @@ export default CoCreateApi;
412
411
  * Provider-specific operation/action name.
413
412
  *
414
413
  * @name {name}
415
- * @kind member
416
- * @attribute
414
+ * @kind attribute
417
415
  * @valueType string
418
416
  * @environment client
419
417
  */
@@ -422,8 +420,7 @@ export default CoCreateApi;
422
420
  * Endpoint name or path; may be defined on an ancestor group.
423
421
  *
424
422
  * @name {name}-endpoint
425
- * @kind member
426
- * @attribute
423
+ * @kind attribute
427
424
  * @valueType string
428
425
  * @environment client
429
426
  */
@@ -432,8 +429,7 @@ export default CoCreateApi;
432
429
  * Provider or HTTP method.
433
430
  *
434
431
  * @name {name}-method
435
- * @kind member
436
- * @attribute
432
+ * @kind attribute
437
433
  * @valueType string
438
434
  * @environment client
439
435
  */
@@ -442,8 +438,7 @@ export default CoCreateApi;
442
438
  * Maps an element's value into request data or maps response data back to the element. A key ending in [] accumulates values into an array; {} maps the whole object.
443
439
  *
444
440
  * @name {name}-key
445
- * @kind member
446
- * @attribute
441
+ * @kind attribute
447
442
  * @valueType string
448
443
  * @environment client
449
444
  */
@@ -452,8 +447,7 @@ export default CoCreateApi;
452
447
  * Limits automatic requests to matching event types.
453
448
  *
454
449
  * @name {name}-event
455
- * @kind member
456
- * @attribute
450
+ * @kind attribute
457
451
  * @valueType string
458
452
  * @environment client
459
453
  */
@@ -462,8 +456,7 @@ export default CoCreateApi;
462
456
  * Excludes an element from request collection or response mapping when set to false.
463
457
  *
464
458
  * @name {name}-request | {name}-response
465
- * @kind member
466
- * @attribute
459
+ * @kind attribute
467
460
  * @valueType boolean-like string
468
461
  * @acceptedValues false
469
462
  * @environment client
package/src/server.js CHANGED
@@ -31,8 +31,14 @@ import {
31
31
  let server = null;
32
32
  let crud = null;
33
33
 
34
+ function sendToServer(data) {
35
+ const envelope = { ...data };
36
+ return server.send(envelope);
37
+ }
38
+
34
39
  const API = {
35
40
  send,
41
+ http,
36
42
  webhook,
37
43
  getApiConfig
38
44
  };
@@ -106,7 +112,7 @@ function createTenantProxy(target, orgId, host) {
106
112
  function createSandbox(context) {
107
113
  const isPlatformOrg = server?.organization_id && (context.organization_id === server.organization_id);
108
114
  const secureCrud = createTenantProxy(context.crud, context.organization_id, context.host);
109
- const secureWs = createTenantProxy(context.wsManager, context.organization_id, context.host);
115
+ const secureWs = createTenantProxy({ send: payload => server.send(payload) }, context.organization_id, context.host);
110
116
 
111
117
  const sandbox = {
112
118
  // Provider fields are configuration variables. For example, a
@@ -183,7 +189,6 @@ function createSandbox(context) {
183
189
  * @param {Object} [data.searchParams] - Query parameters appended to the request URL.
184
190
  * @param {Object} [data.headers] - Custom HTTP header directives.
185
191
  * @param {number} [data.timeout=15000] - Request timeout in milliseconds.
186
- * @param {Object} [data.socket] - WebSocket client reference for real-time response emit.
187
192
  * @param {string} [data.organization_id] - Multi-tenant organization identifier.
188
193
  * @param {string} [data.host] - Target host domain.
189
194
  * @param {Object|null} [parentContext=null] - Outer sandbox execution context when nested.
@@ -195,8 +200,8 @@ function createSandbox(context) {
195
200
  export async function send(data, parentContext = null) {
196
201
  try {
197
202
  const wsManager = server?.wsManager;
198
- const orgId = parentContext?.organization_id || data.socket?.organization_id || data.organization_id;
199
- const host = parentContext?.host || data.socket?.host || data.host;
203
+ const orgId = parentContext?.organization_id || data.organization_id;
204
+ const host = parentContext?.host || data.host;
200
205
 
201
206
  const apiName = data.api?.trim() || "";
202
207
  const endpoint = data.endpoint?.trim() || "";
@@ -297,9 +302,7 @@ export async function send(data, parentContext = null) {
297
302
 
298
303
  if (request.resolved) {
299
304
  data.data = request.data
300
- if (data.socket && wsManager) {
301
- wsManager.send(data);
302
- }
305
+ sendToServer(data);
303
306
  return data;
304
307
  }
305
308
 
@@ -342,9 +345,7 @@ export async function send(data, parentContext = null) {
342
345
  const response = await makeHttpRequest(url, options);
343
346
  data.data = await parseResponseData(response);
344
347
 
345
- if (data.socket && wsManager) {
346
- wsManager.send(data);
347
- }
348
+ sendToServer(data);
348
349
  return data;
349
350
  } catch (error) {
350
351
  const wsManager = server?.wsManager;
@@ -358,12 +359,88 @@ export async function send(data, parentContext = null) {
358
359
  data.statusText = error.response.statusText;
359
360
  data.responseData = error.response.data;
360
361
  }
361
- if (data.socket && wsManager) {
362
- wsManager.send(data);
363
- return data;
362
+ sendToServer(data);
363
+ return data;
364
+ }
365
+ }
366
+
367
+ /**
368
+ * Handles inbound API HTTP requests, resolves host scope and authorizes before execution.
369
+ * @param {object} req - Native HTTP request.
370
+ * @param {object} res - Native HTTP response.
371
+ * @param {object} [parsedInput] - Body already read by the manager HTTP entrance.
372
+ * @param {Function} [execute] - Trusted dispatcher invoked only after request authorization.
373
+ * @returns {Promise<object|undefined>} Successful execution result, otherwise undefined.
374
+ * @public
375
+ * @environment server
376
+ */
377
+ export async function http(req, res, parsedInput, execute = request => server.api.send(request)) {
378
+ const reply = (status, body) => {
379
+ res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
380
+ res.end(JSON.stringify(body));
381
+ };
382
+ if (req.method !== 'POST') {
383
+ res.setHeader('Allow', 'POST');
384
+ return reply(405, { error: 'Use POST for this operation.' });
385
+ }
386
+ if (req.headers['content-type']?.split(';')[0].trim().toLowerCase() !== 'application/json') {
387
+ return reply(415, { error: 'An application/json body is required.' });
388
+ }
389
+ let input = parsedInput;
390
+ try {
391
+ if (input === undefined) {
392
+ const chunks = [];
393
+ let size = 0;
394
+ for await (const chunk of req) {
395
+ const buffer = Buffer.from(chunk);
396
+ size += buffer.length;
397
+ if (size > 1024 * 1024) return reply(413, { error: 'Request body exceeds 1 MiB.' });
398
+ chunks.push(buffer);
399
+ }
400
+ input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
364
401
  }
365
- throw error;
402
+ if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error();
403
+ } catch {
404
+ return reply(400, { error: 'A JSON object is required.' });
366
405
  }
406
+
407
+ const bearer = req.headers.authorization?.match(/^Bearer\s+(\S+)$/i)?.[1];
408
+ const apikey = bearer || input.apikey;
409
+ if ((apikey !== undefined && (typeof apikey !== 'string' || !apikey.trim())) ||
410
+ (bearer && input.apikey !== undefined && input.apikey !== bearer)) {
411
+ return reply(401, { error: 'A valid API key is required.' });
412
+ }
413
+
414
+ try {
415
+ const host = new URL(`https://${req.headers.host}`).hostname;
416
+ const organization = await server.crud.getOrganization({ host });
417
+ if (!organization?._id || organization.error) return reply(404, { error: 'Organization not found.' });
418
+ if (typeof input.api !== 'string' || !input.api.trim() ||
419
+ typeof input.endpoint !== 'string' || !input.endpoint.trim() ||
420
+ typeof input.method !== 'string' || !input.method.trim()) {
421
+ return reply(400, { error: 'api, endpoint and method are required.' });
422
+ }
423
+ const envelope = pickHttpFields(input, ['api', 'endpoint', 'method', 'data', 'region', 'headers', 'searchParams', 'timeout']);
424
+ // Scope and identity are server-resolved, never supplied by the caller.
425
+ Object.assign(envelope, { organization_id: organization._id, host, apikey });
426
+ const request = await server.authorize?.request(envelope);
427
+ if (!request) return reply(403, { error: 'Operation is not authorized.' });
428
+ const result = await execute(request);
429
+ const failed = result?.success === false || hasHttpErrors(result?.error);
430
+ reply(failed ? 400 : 200, result);
431
+ return failed ? undefined : result;
432
+ } catch (error) {
433
+ if (error.code === 'AUTHORIZATION_DENIED') return reply(403, { error: error.message });
434
+ return reply(500, { error: 'Unable to process the operation.' });
435
+ }
436
+ }
437
+
438
+ function hasHttpErrors(error) {
439
+ return Array.isArray(error) ? error.length > 0 : Boolean(error);
440
+ }
441
+
442
+ function pickHttpFields(input, fields) {
443
+ return Object.fromEntries(fields.filter(field => Object.hasOwn(input, field)).map(field => [field, input[field]]));
367
444
  }
368
445
 
369
446
  /**
@@ -0,0 +1,47 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { init, send } from '../src/server.js';
4
+
5
+ test('API responses and errors enter server.send instead of raw socket delivery', async t => {
6
+ const sent = [];
7
+ await init({ organization_id: 'platform', crud: {},
8
+ send: data => { sent.push(data); return data; },
9
+ wsManager: { send() { assert.fail('API must use server.send'); } } });
10
+ t.mock.method(globalThis, 'fetch', async () => new Response('{"ok":true}', { headers: { 'content-type': 'application/json' } }));
11
+ const data = { method: 'get', url: 'https://example.test', organization_id: 'tenant',
12
+ socketId: 'trusted-socket', clientId: 'trusted-client', host: 'tenant.test',
13
+ socket: { organization_id: 'forged-org', host: 'forged.test' } };
14
+ assert.equal(await send(data), data);
15
+ assert.deepEqual(data.data, { ok: true });
16
+ assert.notEqual(sent[0], data);
17
+ assert.equal(sent[0].socket, data.socket);
18
+ assert.equal(sent[0].socketId, 'trusted-socket');
19
+ assert.equal(sent[0].clientId, 'trusted-client');
20
+ const missing = { organization_id: 'tenant', host: 'tenant.test' };
21
+ assert.equal(await send(missing), missing);
22
+ assert.match(missing.error[0], /endpoint.*url/);
23
+ assert.equal(sent[1].socket, undefined);
24
+ assert.equal(sent[1].organization_id, 'tenant');
25
+ });
26
+
27
+ test('API AST socket operators retain tenant scope while entering server.send', async () => {
28
+ const sent = [];
29
+ await init({ organization_id: 'platform',
30
+ crud: { send: async request => ({ object: request.array === 'apis'
31
+ ? [{ _id: 'provider', url: 'https://example.test' }]
32
+ : [{ resolved: true, data: { '$socket.send': { method: 'notification', organization_id: 'forged', host: 'forged' } } }] }) },
33
+ send: data => { sent.push({ ...data }); return data; },
34
+ wsManager: { send() { assert.fail('AST must use server.send'); } } });
35
+ const data = { method: 'post', api: 'provider', endpoint: 'notify', organization_id: 'tenant',
36
+ socketId: 'trusted-socket', clientId: 'trusted-client', host: 'tenant.test',
37
+ socket: { organization_id: 'forged-org', host: 'forged.test' } };
38
+ await send(data);
39
+ assert.equal(data.error, undefined);
40
+ assert.equal(sent[0].method, 'notification');
41
+ assert.equal(sent[0].organization_id, 'tenant');
42
+ assert.equal(sent[0].host, 'tenant.test');
43
+ assert.equal(sent[0].socket, undefined);
44
+ assert.equal(sent[1].socket, data.socket);
45
+ assert.equal(sent[1].socketId, 'trusted-socket');
46
+ assert.equal(sent.length, 2);
47
+ });