@erxes/plugin-sdk 0.1.0-v2.16 → 0.1.0-v2.17
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 +4 -3
- package/dist/openapi.d.ts +9 -7
- package/dist/openapi.js +46 -15
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -121,11 +121,12 @@
|
|
|
121
121
|
* .where(compileFilter(FIELDS, input.filter, { me: member.userId })) // filter: FilterParam
|
|
122
122
|
*
|
|
123
123
|
* API reference: `@erxes/plugin-sdk/openapi` documents the plugin's routes, served as REST beside
|
|
124
|
-
* the RPC handler
|
|
124
|
+
* the RPC handler. The manifest's `api.docs` lists one document per audience (`member`, and
|
|
125
|
+
* `customer` or `website` for routes those call), and Settings › Developer shows them:
|
|
125
126
|
*
|
|
126
|
-
* api: { url: `${publicUrl}/api`,
|
|
127
|
+
* api: { url: `${publicUrl}/api`, docs: [{ audience: 'member', path: '/openapi/member.json' }] },
|
|
127
128
|
* 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
|
+
* app.get('/api/openapi/member.json', async (_req, res) => res.json(await pluginOpenApi(router, { plugin, audience: 'member', title, version, prefix: '/v1' })));
|
|
129
130
|
*
|
|
130
131
|
* The client secret is only ever sent to `POST /plugins/token`; API calls use
|
|
131
132
|
* 15-minute tokens, fetched and renewed here. Plugins on core's database can
|
package/dist/openapi.d.ts
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
|
+
import { PluginApiAudience } from "@erxes/core-contract";
|
|
1
2
|
import { OpenAPI, OpenAPIGenerator } from "@orpc/openapi";
|
|
2
3
|
/** What `OpenAPIGenerator` documents: a router or a contract. */
|
|
3
4
|
type Documented = Parameters<OpenAPIGenerator['generate']>[0];
|
|
4
5
|
export interface PluginOpenApiOptions {
|
|
5
6
|
/** The plugin's name, as registered (`sales`). */
|
|
6
7
|
plugin: string;
|
|
8
|
+
/** Who calls these routes, which decides how they sign in (the manifest's `api.docs`). */
|
|
9
|
+
audience: PluginApiAudience;
|
|
7
10
|
title: string;
|
|
8
11
|
version: string;
|
|
9
12
|
description?: string;
|
|
@@ -14,14 +17,13 @@ export interface PluginOpenApiOptions {
|
|
|
14
17
|
prefix: `/${string}`;
|
|
15
18
|
}
|
|
16
19
|
/**
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* with an API key; the document says how.
|
|
20
|
+
* One OpenAPI document of a plugin's REST routes, for Settings › Developer › API reference:
|
|
21
|
+
* serve it at its path in the manifest's `api.docs` (`/openapi/member.json` under `api.url`).
|
|
22
|
+
* Each audience signs in its own way (`securityOf`), and the document says how.
|
|
21
23
|
*
|
|
22
24
|
* const rest = new OpenAPIHandler(router); // mounted at `<api path>/v1`, like the RPC handler
|
|
23
|
-
* const doc = pluginOpenApi(router, { plugin: 'sales',
|
|
24
|
-
* app.get('/api/openapi.json', async (_req, res) => res.json(await doc));
|
|
25
|
+
* const doc = pluginOpenApi(router, { plugin: 'sales', audience: 'member', title, version, prefix: '/v1' });
|
|
26
|
+
* app.get('/api/openapi/member.json', async (_req, res) => res.json(await doc));
|
|
25
27
|
*/
|
|
26
|
-
export declare const pluginOpenApi: (router: Documented, { plugin, title, version, description, prefix }: PluginOpenApiOptions) => Promise<OpenAPI.Document>;
|
|
28
|
+
export declare const pluginOpenApi: (router: Documented, { plugin, audience, title, version, description, prefix }: PluginOpenApiOptions) => Promise<OpenAPI.Document>;
|
|
27
29
|
export {};
|
package/dist/openapi.js
CHANGED
|
@@ -1,31 +1,62 @@
|
|
|
1
|
-
import { CORE_API_PREFIX, PLUGIN_SESSION_SCHEME } from "@erxes/core-contract";
|
|
1
|
+
import { CORE_API_PREFIX, CUSTOMER_TOKEN_SCHEME, PLUGIN_SESSION_SCHEME, WEBSITE_KEY_SCHEME } from "@erxes/core-contract";
|
|
2
2
|
import { OpenAPIGenerator } from "@orpc/openapi";
|
|
3
3
|
import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
|
|
4
4
|
// src/openapi.ts
|
|
5
|
+
const BEARER = {
|
|
6
|
+
type: "http",
|
|
7
|
+
scheme: "bearer",
|
|
8
|
+
bearerFormat: "JWT"
|
|
9
|
+
};
|
|
10
|
+
const customerToken = {
|
|
11
|
+
...BEARER,
|
|
12
|
+
description: `A customer's access token from core: \`POST ${CORE_API_PREFIX}/customer-auth/sign-in\` returns it (core's Customer API documents the sign-in).`
|
|
13
|
+
};
|
|
14
|
+
/** How each audience signs in, for the document's security schemes. */
|
|
15
|
+
const securityOf = (plugin, audience) => {
|
|
16
|
+
if (audience === "member") return {
|
|
17
|
+
components: { securitySchemes: { [PLUGIN_SESSION_SCHEME]: {
|
|
18
|
+
...BEARER,
|
|
19
|
+
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.`
|
|
20
|
+
} } },
|
|
21
|
+
security: [{ [PLUGIN_SESSION_SCHEME]: [] }]
|
|
22
|
+
};
|
|
23
|
+
if (audience === "customer") return {
|
|
24
|
+
components: { securitySchemes: { [CUSTOMER_TOKEN_SCHEME]: customerToken } },
|
|
25
|
+
security: [{ [CUSTOMER_TOKEN_SCHEME]: [] }]
|
|
26
|
+
};
|
|
27
|
+
return {
|
|
28
|
+
components: { securitySchemes: {
|
|
29
|
+
[WEBSITE_KEY_SCHEME]: {
|
|
30
|
+
type: "apiKey",
|
|
31
|
+
in: "header",
|
|
32
|
+
name: "x-api-key",
|
|
33
|
+
description: "The website's key, from the plugin's settings. Keep it on the server."
|
|
34
|
+
},
|
|
35
|
+
[CUSTOMER_TOKEN_SCHEME]: customerToken
|
|
36
|
+
} },
|
|
37
|
+
security: [{ [WEBSITE_KEY_SCHEME]: [] }, {
|
|
38
|
+
[WEBSITE_KEY_SCHEME]: [],
|
|
39
|
+
[CUSTOMER_TOKEN_SCHEME]: []
|
|
40
|
+
}]
|
|
41
|
+
};
|
|
42
|
+
};
|
|
5
43
|
/**
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* with an API key; the document says how.
|
|
44
|
+
* One OpenAPI document of a plugin's REST routes, for Settings › Developer › API reference:
|
|
45
|
+
* serve it at its path in the manifest's `api.docs` (`/openapi/member.json` under `api.url`).
|
|
46
|
+
* Each audience signs in its own way (`securityOf`), and the document says how.
|
|
10
47
|
*
|
|
11
48
|
* const rest = new OpenAPIHandler(router); // mounted at `<api path>/v1`, like the RPC handler
|
|
12
|
-
* const doc = pluginOpenApi(router, { plugin: 'sales',
|
|
13
|
-
* app.get('/api/openapi.json', async (_req, res) => res.json(await doc));
|
|
49
|
+
* const doc = pluginOpenApi(router, { plugin: 'sales', audience: 'member', title, version, prefix: '/v1' });
|
|
50
|
+
* app.get('/api/openapi/member.json', async (_req, res) => res.json(await doc));
|
|
14
51
|
*/
|
|
15
|
-
const pluginOpenApi = async (router, { plugin, title, version, description, prefix }) => {
|
|
52
|
+
const pluginOpenApi = async (router, { plugin, audience, title, version, description, prefix }) => {
|
|
16
53
|
const doc = await new OpenAPIGenerator({ schemaConverters: [new ZodToJsonSchemaConverter()] }).generate(router, {
|
|
17
54
|
info: {
|
|
18
55
|
title,
|
|
19
56
|
version,
|
|
20
57
|
description
|
|
21
58
|
},
|
|
22
|
-
|
|
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]: [] }]
|
|
59
|
+
...securityOf(plugin, audience)
|
|
29
60
|
});
|
|
30
61
|
doc.paths = Object.fromEntries(Object.entries(doc.paths ?? {}).map(([path, item]) => [`${prefix}${path}`, item]));
|
|
31
62
|
return doc;
|
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.17",
|
|
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",
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"@orpc/zod": "1.16.2",
|
|
37
37
|
"jose": "^6.2.17",
|
|
38
38
|
"zod": "^4.6.7",
|
|
39
|
-
"@erxes/core-contract": "0.1.0-v2.
|
|
39
|
+
"@erxes/core-contract": "0.1.0-v2.19"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"drizzle-orm": "0.45.4"
|