@erxes/plugin-sdk 0.1.0-v2.12 → 0.1.0-v2.14
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 +13 -0
- package/dist/openapi.d.ts +27 -0
- package/dist/openapi.js +33 -0
- package/package.json +5 -2
package/dist/index.d.ts
CHANGED
|
@@ -29,6 +29,12 @@
|
|
|
29
29
|
* // An invoice may list what it pays for; `plugin` names another plugin's line (it gets the events):
|
|
30
30
|
* // lines: [{ productId, quantity: 1, unitPrice: 150000 }, { name: 'Delivery', quantity: 1, unitPrice: 10000, plugin: 'tms' }]
|
|
31
31
|
*
|
|
32
|
+
* Team members who don't sign in (scope `users:write`): people a plugin keeps on the team for its own app
|
|
33
|
+
* (HR's employees). They take no seat and never sign in to erxes; a plugin adds them and changes
|
|
34
|
+
* their profile, never a member who signs in.
|
|
35
|
+
*
|
|
36
|
+
* const worker = await core.forOrg(orgId).users.add({ fullName, employeeId, phone });
|
|
37
|
+
*
|
|
32
38
|
* Branches and departments (scopes `units:read`, `units:write`; subscribe to `core.unit.*`): core's,
|
|
33
39
|
* shared by plugins. Keep a read-only copy for your own visibility queries and refresh it whenever
|
|
34
40
|
* a `core.unit.*` event arrives (the event names the unit in `entityId`); bring your old units in
|
|
@@ -114,6 +120,13 @@
|
|
|
114
120
|
* const FIELDS = { 'subject.name': { type: 'text', expr: tickets.name } } satisfies FilterFields;
|
|
115
121
|
* .where(compileFilter(FIELDS, input.filter, { me: member.userId })) // filter: FilterParam
|
|
116
122
|
*
|
|
123
|
+
* API reference: `@erxes/plugin-sdk/openapi` documents the plugin's routes, served as REST beside
|
|
124
|
+
* the RPC handler; the manifest's `api.openapi` names the path, and Settings › Developer shows it:
|
|
125
|
+
*
|
|
126
|
+
* api: { url: `${publicUrl}/api`, openapi: '/openapi.json' },
|
|
127
|
+
* app.use('/api/v1', member check, (req, res, next) => rest.handle(req, res, { prefix: '/api/v1', context }));
|
|
128
|
+
* app.get('/api/openapi.json', async (_req, res) => res.json(await pluginOpenApi(router, { plugin, title, version, prefix: '/v1' })));
|
|
129
|
+
*
|
|
117
130
|
* The client secret is only ever sent to `POST /plugins/token`; API calls use
|
|
118
131
|
* 15-minute tokens, fetched and renewed here. Plugins on core's database can
|
|
119
132
|
* 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.14",
|
|
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.16"
|
|
37
40
|
},
|
|
38
41
|
"devDependencies": {
|
|
39
42
|
"drizzle-orm": "0.45.4"
|