@well-known-js/core 1.0.3 → 1.1.0
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/README.md +35 -0
- package/dist/index.d.ts +10 -1
- package/dist/index.js +33 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -34,6 +34,41 @@ The package also exports the contracts used to create providers and framework ad
|
|
|
34
34
|
- `WellKnownProviderInstance` describes a configured provider;
|
|
35
35
|
- `WellKnownGeneratedFile` describes the generated path, filename, content type, and body.
|
|
36
36
|
|
|
37
|
+
## Custom resources
|
|
38
|
+
|
|
39
|
+
Use `custom()` to serve a resource without a dedicated provider package:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { custom, defineConfig } from "@well-known-js/core";
|
|
43
|
+
|
|
44
|
+
export default defineConfig({
|
|
45
|
+
providers: [
|
|
46
|
+
custom({
|
|
47
|
+
path: "/.well-known/example.json",
|
|
48
|
+
contentType: "application/json",
|
|
49
|
+
body: JSON.stringify({ enabled: true }),
|
|
50
|
+
}),
|
|
51
|
+
custom({
|
|
52
|
+
path: "/.well-known/example.txt",
|
|
53
|
+
contentType: "text/plain; charset=utf-8",
|
|
54
|
+
body: "Hello, world!\n",
|
|
55
|
+
}),
|
|
56
|
+
],
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`CustomOptions` requires `path`, `contentType`, and a string `body`; `name` is optional and defaults
|
|
61
|
+
to `"custom"`. The body is preserved as supplied, including whitespace. Serialize JSON with
|
|
62
|
+
`JSON.stringify()` before passing it in.
|
|
63
|
+
|
|
64
|
+
Paths must start with `/.well-known/`. Nested paths are supported; each segment may contain letters,
|
|
65
|
+
digits, `.`, `_`, `~`, and `-`, but cannot be `.` or `..`. Empty segments, percent encoding,
|
|
66
|
+
backslashes, query strings, and fragments are rejected. Configuration is validated when `custom()`
|
|
67
|
+
is called, and `defineConfig()` rejects duplicate paths as with other providers.
|
|
68
|
+
|
|
69
|
+
Custom providers work with all framework adapters. Static file integrations write the body to the
|
|
70
|
+
public directory; server integrations also use the supplied content type for the response.
|
|
71
|
+
|
|
37
72
|
## Providers
|
|
38
73
|
|
|
39
74
|
- [`@well-known-js/agent-card`](https://www.npmjs.com/package/@well-known-js/agent-card)
|
package/dist/index.d.ts
CHANGED
|
@@ -20,4 +20,13 @@ interface WellKnownConfig {
|
|
|
20
20
|
}
|
|
21
21
|
declare function defineConfig(config: WellKnownConfig): WellKnownConfig;
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
interface CustomOptions {
|
|
24
|
+
path: `/.well-known/${string}`;
|
|
25
|
+
contentType: string;
|
|
26
|
+
body: string;
|
|
27
|
+
name?: string;
|
|
28
|
+
}
|
|
29
|
+
/** Create a provider for a custom text resource, including pre-serialized JSON. */
|
|
30
|
+
declare function custom(options: CustomOptions): WellKnownProviderInstance;
|
|
31
|
+
|
|
32
|
+
export { type CustomOptions, type WellKnownConfig, type WellKnownGeneratedFile, type WellKnownProvider, type WellKnownProviderInstance, custom, defineConfig };
|
package/dist/index.js
CHANGED
|
@@ -9,6 +9,39 @@ function defineConfig(config) {
|
|
|
9
9
|
}
|
|
10
10
|
return config;
|
|
11
11
|
}
|
|
12
|
+
|
|
13
|
+
// src/custom.ts
|
|
14
|
+
function custom(options) {
|
|
15
|
+
const { path, contentType, body, name = "custom" } = options;
|
|
16
|
+
const prefix = "/.well-known/";
|
|
17
|
+
const segments = typeof path === "string" ? path.slice(prefix.length).split("/") : [];
|
|
18
|
+
if (typeof path !== "string" || !path.startsWith(prefix) || segments.some(
|
|
19
|
+
(segment) => !segment || /[^A-Za-z0-9._~-]/.test(segment) || segment === "." || segment === ".."
|
|
20
|
+
)) {
|
|
21
|
+
throw new Error("Custom path must be a file under /.well-known/ with safe path segments.");
|
|
22
|
+
}
|
|
23
|
+
if (typeof contentType !== "string" || /[^\t\x20-\x7e]/.test(contentType) || !/^[-!#$%&'*+.^_`|~A-Za-z0-9]+\/[-!#$%&'*+.^_`|~A-Za-z0-9]+(?:[ \t]*;[^\r\n\0]+)?$/.test(
|
|
24
|
+
contentType
|
|
25
|
+
)) {
|
|
26
|
+
throw new Error(
|
|
27
|
+
"Custom contentType must be a media type, such as text/plain; charset=utf-8."
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
if (typeof body !== "string") {
|
|
31
|
+
throw new Error("Custom body must be a string. Use JSON.stringify() for JSON resources.");
|
|
32
|
+
}
|
|
33
|
+
return {
|
|
34
|
+
name,
|
|
35
|
+
path,
|
|
36
|
+
generate: () => ({
|
|
37
|
+
path,
|
|
38
|
+
filename: segments[segments.length - 1],
|
|
39
|
+
contentType,
|
|
40
|
+
body
|
|
41
|
+
})
|
|
42
|
+
};
|
|
43
|
+
}
|
|
12
44
|
export {
|
|
45
|
+
custom,
|
|
13
46
|
defineConfig
|
|
14
47
|
};
|
package/package.json
CHANGED