@well-known-js/core 1.0.2 → 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 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
- export { type WellKnownConfig, type WellKnownGeneratedFile, type WellKnownProvider, type WellKnownProviderInstance, defineConfig };
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
@@ -1,7 +1,15 @@
1
1
  {
2
2
  "name": "@well-known-js/core",
3
- "version": "1.0.2",
3
+ "version": "1.1.0",
4
4
  "description": "Core utilities and types for generating .well-known files.",
5
+ "homepage": "https://www.bryanledda.fr/fr/products/tools/well-known-js",
6
+ "keywords": [
7
+ "well-known",
8
+ "typescript",
9
+ "web-standards",
10
+ "metadata",
11
+ "service-discovery"
12
+ ],
5
13
  "license": "MIT",
6
14
  "repository": {
7
15
  "type": "git",