@erxes/plugin-sdk 0.1.0-v2.11 → 0.1.0-v2.13
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/dist/index.d.ts +10 -1
- package/dist/openapi.d.ts +27 -0
- package/dist/openapi.js +33 -0
- package/package.json +5 -2
package/dist/index.d.ts
CHANGED
|
@@ -32,7 +32,9 @@
|
|
|
32
32
|
* Branches and departments (scopes `units:read`, `units:write`; subscribe to `core.unit.*`): core's,
|
|
33
33
|
* shared by plugins. Keep a read-only copy for your own visibility queries and refresh it whenever
|
|
34
34
|
* a `core.unit.*` event arrives (the event names the unit in `entityId`); bring your old units in
|
|
35
|
-
* once with `units.import`, which keeps their ids and answers where each one went.
|
|
35
|
+
* once with `units.import`, which keeps their ids and answers where each one went. Each unit has a
|
|
36
|
+
* `typeId`, one of the organisation's `unitTypes` of its kind (Branch and Department to start);
|
|
37
|
+
* bring your own types first with `unitTypes.import` and name them on the units you import.
|
|
36
38
|
*
|
|
37
39
|
* const { data } = await core.forOrg(orgId).units.list({}); // every unit, parents first, with memberIds
|
|
38
40
|
* const { ids } = await core.forOrg(orgId).units.import({ units: [{ id, kind: 'branch', name, memberIds }] });
|
|
@@ -112,6 +114,13 @@
|
|
|
112
114
|
* const FIELDS = { 'subject.name': { type: 'text', expr: tickets.name } } satisfies FilterFields;
|
|
113
115
|
* .where(compileFilter(FIELDS, input.filter, { me: member.userId })) // filter: FilterParam
|
|
114
116
|
*
|
|
117
|
+
* API reference: `@erxes/plugin-sdk/openapi` documents the plugin's routes, served as REST beside
|
|
118
|
+
* the RPC handler; the manifest's `api.openapi` names the path, and Settings › Developer shows it:
|
|
119
|
+
*
|
|
120
|
+
* api: { url: `${publicUrl}/api`, openapi: '/openapi.json' },
|
|
121
|
+
* app.use('/api/v1', member check, (req, res, next) => rest.handle(req, res, { prefix: '/api/v1', context }));
|
|
122
|
+
* app.get('/api/openapi.json', async (_req, res) => res.json(await pluginOpenApi(router, { plugin, title, version, prefix: '/v1' })));
|
|
123
|
+
*
|
|
115
124
|
* The client secret is only ever sent to `POST /plugins/token`; API calls use
|
|
116
125
|
* 15-minute tokens, fetched and renewed here. Plugins on core's database can
|
|
117
126
|
* also call `core_publish_event()`, `core_record_audit()` and
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { OpenAPI, OpenAPIGenerator } from "@orpc/openapi";
|
|
2
|
+
/** What `OpenAPIGenerator` documents: a router or a contract. */
|
|
3
|
+
type Documented = Parameters<OpenAPIGenerator['generate']>[0];
|
|
4
|
+
export interface PluginOpenApiOptions {
|
|
5
|
+
/** The plugin's name, as registered (`sales`). */
|
|
6
|
+
plugin: string;
|
|
7
|
+
title: string;
|
|
8
|
+
version: string;
|
|
9
|
+
description?: string;
|
|
10
|
+
/**
|
|
11
|
+
* Where the REST routes are served under the manifest's `api.url` (`/v1`, for an
|
|
12
|
+
* `OpenAPIHandler` with prefix `<api path>/v1`): every path in the document starts with it.
|
|
13
|
+
*/
|
|
14
|
+
prefix: `/${string}`;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The OpenAPI document of a plugin's REST routes, for Settings › Developer › API
|
|
18
|
+
* reference: serve it at the manifest's `api.openapi` (`/openapi.json` under `api.url`).
|
|
19
|
+
* Calls carry a member's 5-minute plugin session token, which a script gets from core
|
|
20
|
+
* with an API key; the document says how.
|
|
21
|
+
*
|
|
22
|
+
* const rest = new OpenAPIHandler(router); // mounted at `<api path>/v1`, like the RPC handler
|
|
23
|
+
* const doc = pluginOpenApi(router, { plugin: 'sales', title: 'Sales', version, prefix: '/v1' });
|
|
24
|
+
* app.get('/api/openapi.json', async (_req, res) => res.json(await doc));
|
|
25
|
+
*/
|
|
26
|
+
export declare const pluginOpenApi: (router: Documented, { plugin, title, version, description, prefix }: PluginOpenApiOptions) => Promise<OpenAPI.Document>;
|
|
27
|
+
export {};
|
package/dist/openapi.js
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { CORE_API_PREFIX, PLUGIN_SESSION_SCHEME } from "@erxes/core-contract";
|
|
2
|
+
import { OpenAPIGenerator } from "@orpc/openapi";
|
|
3
|
+
import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
|
|
4
|
+
// src/openapi.ts
|
|
5
|
+
/**
|
|
6
|
+
* The OpenAPI document of a plugin's REST routes, for Settings › Developer › API
|
|
7
|
+
* reference: serve it at the manifest's `api.openapi` (`/openapi.json` under `api.url`).
|
|
8
|
+
* Calls carry a member's 5-minute plugin session token, which a script gets from core
|
|
9
|
+
* with an API key; the document says how.
|
|
10
|
+
*
|
|
11
|
+
* const rest = new OpenAPIHandler(router); // mounted at `<api path>/v1`, like the RPC handler
|
|
12
|
+
* const doc = pluginOpenApi(router, { plugin: 'sales', title: 'Sales', version, prefix: '/v1' });
|
|
13
|
+
* app.get('/api/openapi.json', async (_req, res) => res.json(await doc));
|
|
14
|
+
*/
|
|
15
|
+
const pluginOpenApi = async (router, { plugin, title, version, description, prefix }) => {
|
|
16
|
+
const doc = await new OpenAPIGenerator({ schemaConverters: [new ZodToJsonSchemaConverter()] }).generate(router, {
|
|
17
|
+
info: {
|
|
18
|
+
title,
|
|
19
|
+
version,
|
|
20
|
+
description
|
|
21
|
+
},
|
|
22
|
+
components: { securitySchemes: { [PLUGIN_SESSION_SCHEME]: {
|
|
23
|
+
type: "http",
|
|
24
|
+
scheme: "bearer",
|
|
25
|
+
bearerFormat: "JWT",
|
|
26
|
+
description: `A member's 5-minute session token for this plugin: \`POST ${CORE_API_PREFIX}/plugins/${plugin}/session\` on core with an API key (Settings › Developer › API keys) returns it.`
|
|
27
|
+
} } },
|
|
28
|
+
security: [{ [PLUGIN_SESSION_SCHEME]: [] }]
|
|
29
|
+
});
|
|
30
|
+
doc.paths = Object.fromEntries(Object.entries(doc.paths ?? {}).map(([path, item]) => [`${prefix}${path}`, item]));
|
|
31
|
+
return doc;
|
|
32
|
+
};
|
|
33
|
+
export { pluginOpenApi };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@erxes/plugin-sdk",
|
|
3
|
-
"version": "0.1.0-v2.
|
|
3
|
+
"version": "0.1.0-v2.13",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "For erxes plugin servers: a typed core client with automatic plugin tokens, verification of members' plugin session tokens and of core's deliveries, and plugin jobs",
|
|
6
6
|
"license": "AGPL-3.0-only",
|
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
"./client": "./dist/client.js",
|
|
20
20
|
"./filter": "./dist/filter.js",
|
|
21
21
|
"./jobs": "./dist/jobs.js",
|
|
22
|
+
"./openapi": "./dist/openapi.js",
|
|
22
23
|
"./verify": "./dist/verify.js",
|
|
23
24
|
"./package.json": "./package.json"
|
|
24
25
|
},
|
|
@@ -30,10 +31,12 @@
|
|
|
30
31
|
"dependencies": {
|
|
31
32
|
"@orpc/client": "1.16.2",
|
|
32
33
|
"@orpc/contract": "1.16.2",
|
|
34
|
+
"@orpc/openapi": "1.16.2",
|
|
33
35
|
"@orpc/openapi-client": "1.16.2",
|
|
36
|
+
"@orpc/zod": "1.16.2",
|
|
34
37
|
"jose": "^6.2.17",
|
|
35
38
|
"zod": "^4.6.7",
|
|
36
|
-
"@erxes/core-contract": "0.1.0-v2.
|
|
39
|
+
"@erxes/core-contract": "0.1.0-v2.15"
|
|
37
40
|
},
|
|
38
41
|
"devDependencies": {
|
|
39
42
|
"drizzle-orm": "0.45.4"
|