@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 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 {};
@@ -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.11",
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.12"
39
+ "@erxes/core-contract": "0.1.0-v2.15"
37
40
  },
38
41
  "devDependencies": {
39
42
  "drizzle-orm": "0.45.4"