@erxes/plugin-sdk 0.1.0-v2.12 → 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
@@ -114,6 +114,13 @@
114
114
  * const FIELDS = { 'subject.name': { type: 'text', expr: tickets.name } } satisfies FilterFields;
115
115
  * .where(compileFilter(FIELDS, input.filter, { me: member.userId })) // filter: FilterParam
116
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
+ *
117
124
  * The client secret is only ever sent to `POST /plugins/token`; API calls use
118
125
  * 15-minute tokens, fetched and renewed here. Plugins on core's database can
119
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.12",
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.14"
39
+ "@erxes/core-contract": "0.1.0-v2.15"
37
40
  },
38
41
  "devDependencies": {
39
42
  "drizzle-orm": "0.45.4"