wherever-dev 0.21.1 → 0.22.1

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.
Files changed (103) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/dist/assistant-channels.d.ts +242 -0
  3. package/dist/assistant-channels.d.ts.map +1 -0
  4. package/dist/assistant-channels.js +270 -0
  5. package/dist/assistant-channels.js.map +1 -0
  6. package/dist/assistant-controller.d.ts +228 -0
  7. package/dist/assistant-controller.d.ts.map +1 -0
  8. package/dist/assistant-controller.js +314 -0
  9. package/dist/assistant-controller.js.map +1 -0
  10. package/dist/assistant-cron.d.ts +87 -0
  11. package/dist/assistant-cron.d.ts.map +1 -0
  12. package/dist/assistant-cron.js +352 -0
  13. package/dist/assistant-cron.js.map +1 -0
  14. package/dist/assistant-folder.d.ts +161 -0
  15. package/dist/assistant-folder.d.ts.map +1 -0
  16. package/dist/assistant-folder.js +333 -0
  17. package/dist/assistant-folder.js.map +1 -0
  18. package/dist/assistant-schedule.d.ts +236 -0
  19. package/dist/assistant-schedule.d.ts.map +1 -0
  20. package/dist/assistant-schedule.js +454 -0
  21. package/dist/assistant-schedule.js.map +1 -0
  22. package/dist/assistant-scheduler.d.ts +210 -0
  23. package/dist/assistant-scheduler.d.ts.map +1 -0
  24. package/dist/assistant-scheduler.js +472 -0
  25. package/dist/assistant-scheduler.js.map +1 -0
  26. package/dist/assistant-tool-text.d.ts +40 -0
  27. package/dist/assistant-tool-text.d.ts.map +1 -0
  28. package/dist/assistant-tool-text.js +102 -0
  29. package/dist/assistant-tool-text.js.map +1 -0
  30. package/dist/assistant-tools.d.ts +222 -0
  31. package/dist/assistant-tools.d.ts.map +1 -0
  32. package/dist/assistant-tools.js +411 -0
  33. package/dist/assistant-tools.js.map +1 -0
  34. package/dist/cli-requests.d.ts +90 -0
  35. package/dist/cli-requests.d.ts.map +1 -0
  36. package/dist/cli-requests.js +75 -0
  37. package/dist/cli-requests.js.map +1 -0
  38. package/dist/index.js +427 -7
  39. package/dist/index.js.map +1 -1
  40. package/dist/protocol.d.ts +43 -0
  41. package/dist/protocol.d.ts.map +1 -1
  42. package/dist/reply-routing.d.ts +106 -0
  43. package/dist/reply-routing.d.ts.map +1 -0
  44. package/dist/reply-routing.js +174 -0
  45. package/dist/reply-routing.js.map +1 -0
  46. package/dist/session-pool.d.ts +235 -4
  47. package/dist/session-pool.d.ts.map +1 -1
  48. package/dist/session-pool.js +446 -100
  49. package/dist/session-pool.js.map +1 -1
  50. package/dist/telegram-channel.d.ts +275 -0
  51. package/dist/telegram-channel.d.ts.map +1 -0
  52. package/dist/telegram-channel.js +702 -0
  53. package/dist/telegram-channel.js.map +1 -0
  54. package/dist/telegram-files.d.ts +101 -0
  55. package/dist/telegram-files.d.ts.map +1 -0
  56. package/dist/telegram-files.js +145 -0
  57. package/dist/telegram-files.js.map +1 -0
  58. package/dist/telegram-pairing.d.ts +119 -0
  59. package/dist/telegram-pairing.d.ts.map +1 -0
  60. package/dist/telegram-pairing.js +97 -0
  61. package/dist/telegram-pairing.js.map +1 -0
  62. package/dist/telegram-replies.d.ts +140 -0
  63. package/dist/telegram-replies.d.ts.map +1 -0
  64. package/dist/telegram-replies.js +474 -0
  65. package/dist/telegram-replies.js.map +1 -0
  66. package/dist/telegram-token.d.ts +55 -0
  67. package/dist/telegram-token.d.ts.map +1 -0
  68. package/dist/telegram-token.js +86 -0
  69. package/dist/telegram-token.js.map +1 -0
  70. package/dist/web-push.d.ts +167 -0
  71. package/dist/web-push.d.ts.map +1 -0
  72. package/dist/web-push.js +387 -0
  73. package/dist/web-push.js.map +1 -0
  74. package/package.json +1 -1
  75. package/public/_app/immutable/assets/0.hWfYEET-.css +1 -0
  76. package/public/_app/immutable/chunks/Cuh9gHb6.js +2 -0
  77. package/public/_app/immutable/chunks/Cuh9gHb6.js.map +1 -0
  78. package/public/_app/immutable/chunks/DEUwJYqt.js +2 -0
  79. package/public/_app/immutable/chunks/{BQ9B_G4h.js.map → DEUwJYqt.js.map} +1 -1
  80. package/public/_app/immutable/chunks/DSPDB3Gw.js +2 -0
  81. package/public/_app/immutable/chunks/{BUONgvl4.js.map → DSPDB3Gw.js.map} +1 -1
  82. package/public/_app/immutable/entry/{app.BZO7Xckk.js → app.BkV4f8p8.js} +3 -3
  83. package/public/_app/immutable/entry/{app.BZO7Xckk.js.map → app.BkV4f8p8.js.map} +1 -1
  84. package/public/_app/immutable/entry/start.D5TsAoxn.js +2 -0
  85. package/public/_app/immutable/entry/start.D5TsAoxn.js.map +1 -0
  86. package/public/_app/immutable/nodes/{0.Czz2XmZU.js → 0.DR4K9Ylw.js} +3 -3
  87. package/public/_app/immutable/nodes/{0.Czz2XmZU.js.map → 0.DR4K9Ylw.js.map} +1 -1
  88. package/public/_app/immutable/nodes/{1.DDvrriUW.js → 1.DdqkeKC4.js} +2 -2
  89. package/public/_app/immutable/nodes/{1.DDvrriUW.js.map → 1.DdqkeKC4.js.map} +1 -1
  90. package/public/_app/immutable/nodes/2.n5lfdeec.js +122 -0
  91. package/public/_app/immutable/nodes/2.n5lfdeec.js.map +1 -0
  92. package/public/_app/version.json +1 -1
  93. package/public/index.html +11 -11
  94. package/public/service-worker.js +1 -1
  95. package/public/_app/immutable/assets/0.BKJ49K71.css +0 -1
  96. package/public/_app/immutable/chunks/BQ9B_G4h.js +0 -2
  97. package/public/_app/immutable/chunks/BUONgvl4.js +0 -2
  98. package/public/_app/immutable/chunks/DauELski.js +0 -2
  99. package/public/_app/immutable/chunks/DauELski.js.map +0 -1
  100. package/public/_app/immutable/entry/start.DWD60uNu.js +0 -2
  101. package/public/_app/immutable/entry/start.DWD60uNu.js.map +0 -1
  102. package/public/_app/immutable/nodes/2.C7E8EMKX.js +0 -120
  103. package/public/_app/immutable/nodes/2.C7E8EMKX.js.map +0 -1
@@ -0,0 +1,55 @@
1
+ /**
2
+ * The assistant's Telegram BOT TOKEN: resolved in ADR 0007's shape, failing per
3
+ * ADR 0018 (an optional channel's unreadable secret disables THAT channel, it
4
+ * never fails the server).
5
+ *
6
+ * Resolution, first non-empty wins (never argv: there is no flag):
7
+ * 1. `WHEREVER_TELEGRAM_TOKEN`, trimmed;
8
+ * 2. `WHEREVER_TELEGRAM_TOKEN_FILE`, the trimmed CONTENT of that file (the
9
+ * sops-nix / systemd `LoadCredential=` shape);
10
+ * 3. `assistantTelegram.token` in `config.json` (the config dir may be a
11
+ * `0400` secret file, ADR 0006).
12
+ *
13
+ * Decision (recorded in work/notes/observations/telegram-token-and-pairing-decisions.md):
14
+ * a set token file that cannot be read, or is empty, is an ERROR that disables
15
+ * Telegram; it does NOT fall through to the config value. ADR 0007's reasoning
16
+ * for its own token file holds here too: the operator asked for the file, so a
17
+ * file that did not arrive is a failed secret render to report, not a cue to
18
+ * quietly use an older value from the config.
19
+ *
20
+ * Both variables are captured and DELETED from `process.env` at startup
21
+ * (`takeTelegramTokenEnv`, beside the auth-token scrub in `parseArgs`), whether
22
+ * or not Telegram is enabled: the agent's `bash` inherits the server's
23
+ * environment. The FILE is read only by `resolveTelegramToken`, which the
24
+ * server calls only while the assistant is active AND Telegram is enabled.
25
+ */
26
+ export declare const TELEGRAM_TOKEN_ENV = "WHEREVER_TELEGRAM_TOKEN";
27
+ export declare const TELEGRAM_TOKEN_FILE_ENV = "WHEREVER_TELEGRAM_TOKEN_FILE";
28
+ export declare const TELEGRAM_TOKEN_CONFIG_KEY = "assistantTelegram.token";
29
+ /** The two environment variables as captured at startup (before the scrub). */
30
+ export interface TelegramTokenEnv {
31
+ token?: string;
32
+ tokenFile?: string;
33
+ }
34
+ /** Capture both variables, then delete them from `env` (the scrub). */
35
+ export declare function takeTelegramTokenEnv(env?: Record<string, string | undefined>): TelegramTokenEnv;
36
+ export type TelegramTokenResult = {
37
+ ok: true;
38
+ token: string;
39
+ source: string;
40
+ warnings: string[];
41
+ } | {
42
+ ok: false;
43
+ error: string;
44
+ warnings: string[];
45
+ };
46
+ export interface ResolveTelegramTokenInput {
47
+ env: TelegramTokenEnv;
48
+ configToken?: unknown;
49
+ /** Reads a file as UTF-8 (throws when it cannot). */
50
+ readFile: (path: string) => string;
51
+ homedir?: string;
52
+ }
53
+ /** Pure resolution (the file read is injected). Never logs: the caller does. */
54
+ export declare function resolveTelegramToken(input: ResolveTelegramTokenInput): TelegramTokenResult;
55
+ //# sourceMappingURL=telegram-token.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"telegram-token.d.ts","sourceRoot":"","sources":["../src/telegram-token.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,kBAAkB,4BAA4B,CAAC;AAC5D,eAAO,MAAM,uBAAuB,iCAAiC,CAAC;AACtE,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,gBAAgB,CAK5G;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAErD,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,gBAAgB,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,mBAAmB,CAwC1F"}
@@ -0,0 +1,86 @@
1
+ import os from 'node:os';
2
+ import path from 'node:path';
3
+ /**
4
+ * The assistant's Telegram BOT TOKEN: resolved in ADR 0007's shape, failing per
5
+ * ADR 0018 (an optional channel's unreadable secret disables THAT channel, it
6
+ * never fails the server).
7
+ *
8
+ * Resolution, first non-empty wins (never argv: there is no flag):
9
+ * 1. `WHEREVER_TELEGRAM_TOKEN`, trimmed;
10
+ * 2. `WHEREVER_TELEGRAM_TOKEN_FILE`, the trimmed CONTENT of that file (the
11
+ * sops-nix / systemd `LoadCredential=` shape);
12
+ * 3. `assistantTelegram.token` in `config.json` (the config dir may be a
13
+ * `0400` secret file, ADR 0006).
14
+ *
15
+ * Decision (recorded in work/notes/observations/telegram-token-and-pairing-decisions.md):
16
+ * a set token file that cannot be read, or is empty, is an ERROR that disables
17
+ * Telegram; it does NOT fall through to the config value. ADR 0007's reasoning
18
+ * for its own token file holds here too: the operator asked for the file, so a
19
+ * file that did not arrive is a failed secret render to report, not a cue to
20
+ * quietly use an older value from the config.
21
+ *
22
+ * Both variables are captured and DELETED from `process.env` at startup
23
+ * (`takeTelegramTokenEnv`, beside the auth-token scrub in `parseArgs`), whether
24
+ * or not Telegram is enabled: the agent's `bash` inherits the server's
25
+ * environment. The FILE is read only by `resolveTelegramToken`, which the
26
+ * server calls only while the assistant is active AND Telegram is enabled.
27
+ */
28
+ export const TELEGRAM_TOKEN_ENV = 'WHEREVER_TELEGRAM_TOKEN';
29
+ export const TELEGRAM_TOKEN_FILE_ENV = 'WHEREVER_TELEGRAM_TOKEN_FILE';
30
+ export const TELEGRAM_TOKEN_CONFIG_KEY = 'assistantTelegram.token';
31
+ /** Capture both variables, then delete them from `env` (the scrub). */
32
+ export function takeTelegramTokenEnv(env = process.env) {
33
+ const taken = { token: env[TELEGRAM_TOKEN_ENV], tokenFile: env[TELEGRAM_TOKEN_FILE_ENV] };
34
+ delete env[TELEGRAM_TOKEN_ENV];
35
+ delete env[TELEGRAM_TOKEN_FILE_ENV];
36
+ return taken;
37
+ }
38
+ /** Pure resolution (the file read is injected). Never logs: the caller does. */
39
+ export function resolveTelegramToken(input) {
40
+ const warnings = [];
41
+ const blank = (name, v) => {
42
+ if (v !== undefined && v.length > 0 && v.trim().length === 0) {
43
+ warnings.push(`${name} is set but contains only whitespace; treating it as NOT SET (a secret meant to be rendered here did not arrive)`);
44
+ }
45
+ };
46
+ const envToken = input.env.token;
47
+ if (envToken && envToken.trim())
48
+ return { ok: true, token: envToken.trim(), source: TELEGRAM_TOKEN_ENV, warnings };
49
+ blank(TELEGRAM_TOKEN_ENV, envToken);
50
+ const file = input.env.tokenFile;
51
+ if (file && file.trim()) {
52
+ const p = expandTilde(file.trim(), input.homedir ?? os.homedir());
53
+ let contents;
54
+ try {
55
+ contents = input.readFile(p);
56
+ }
57
+ catch (err) {
58
+ return {
59
+ ok: false,
60
+ error: `${TELEGRAM_TOKEN_FILE_ENV} is set to ${p} but it could not be read (${err instanceof Error ? err.message : String(err)})`,
61
+ warnings,
62
+ };
63
+ }
64
+ const trimmed = contents.trim();
65
+ if (!trimmed)
66
+ return { ok: false, error: `${TELEGRAM_TOKEN_FILE_ENV} (${p}) is empty`, warnings };
67
+ return { ok: true, token: trimmed, source: `${TELEGRAM_TOKEN_FILE_ENV} (${p})`, warnings };
68
+ }
69
+ blank(TELEGRAM_TOKEN_FILE_ENV, file);
70
+ if (typeof input.configToken === 'string' && input.configToken.trim()) {
71
+ return { ok: true, token: input.configToken.trim(), source: TELEGRAM_TOKEN_CONFIG_KEY, warnings };
72
+ }
73
+ return {
74
+ ok: false,
75
+ error: `no bot token: set ${TELEGRAM_TOKEN_ENV}, ${TELEGRAM_TOKEN_FILE_ENV} or ${TELEGRAM_TOKEN_CONFIG_KEY}`,
76
+ warnings,
77
+ };
78
+ }
79
+ function expandTilde(p, home) {
80
+ if (p === '~')
81
+ return home;
82
+ if (p.startsWith('~/'))
83
+ return path.join(home, p.slice(2));
84
+ return p;
85
+ }
86
+ //# sourceMappingURL=telegram-token.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"telegram-token.js","sourceRoot":"","sources":["../src/telegram-token.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,167 @@
1
+ import type { AssistantChannel, ChannelNotification, ChannelNotifyResult } from './assistant-channels.js';
2
+ /**
3
+ * Web Push, sent IN-PROCESS by wherever (ADR 0017): the first transport behind
4
+ * the assistant's channel seam (assistant-channels.ts). It implements `notify`
5
+ * only: a push carries a deliberate `assistant_notify`, never a reply (ADR 0014).
6
+ *
7
+ * Dependency-free on purpose (no `web-push` package, so `pnpm-lock.yaml` and the
8
+ * Nix `pnpmDepsHash` are untouched, ADR 0008): `node:crypto` does RFC 8291
9
+ * message encryption (`aes128gcm`, RFC 8188) and RFC 8292 VAPID (an ES256 JWT).
10
+ * The encryption is checked against RFC 8291's Appendix A test vector.
11
+ *
12
+ * State, all in the STATE dir (ADR 0006), all mode 0600 (private key, and each
13
+ * subscription's auth secret), written atomically (tmp + rename):
14
+ * - `assistant-vapid.json`: the VAPID keypair, generated on FIRST USE (the first
15
+ * time the web asks for the public key to subscribe, or a send). Never at
16
+ * start, so an active assistant nobody subscribes to writes nothing.
17
+ * - `assistant-push-subscriptions.json`: every registered subscription. A push
18
+ * goes to EVERY one; a 404 / 410 answer from the push service prunes it.
19
+ *
20
+ * Built only while the assistant is ACTIVE (configured AND this server holds the
21
+ * folder lock), like the scheduler; see `server/src/index.ts`.
22
+ */
23
+ export declare const VAPID_FILE = "assistant-vapid.json";
24
+ export declare const SUBSCRIPTIONS_FILE = "assistant-push-subscriptions.json";
25
+ /** The routing origin / channel name of Web Push (it never originates a user message). */
26
+ export declare const WEB_PUSH_CHANNEL = "webpush";
27
+ /** A browser `PushSubscription.toJSON()`, as the web POSTs it. */
28
+ export interface PushSubscriptionRecord {
29
+ endpoint: string;
30
+ expirationTime?: number | null;
31
+ keys: {
32
+ p256dh: string;
33
+ auth: string;
34
+ };
35
+ }
36
+ export interface VapidKeys {
37
+ /** Uncompressed P-256 point, base64url (the browser's `applicationServerKey`). */
38
+ publicKey: string;
39
+ /** The private scalar `d`, base64url. */
40
+ privateKey: string;
41
+ }
42
+ /** The service worker's declarative payload (`DeclarativePushNotification` in web/src/service-worker/index.ts). */
43
+ export interface DeclarativePushPayload {
44
+ web_push: 8030;
45
+ notification: {
46
+ title: string;
47
+ body: string;
48
+ navigate: string;
49
+ };
50
+ }
51
+ /** The HTTP boundary a push is sent through (the global `fetch` by default; mocked in tests). */
52
+ export type PushFetch = (url: string, init: {
53
+ method: 'POST';
54
+ headers: Record<string, string>;
55
+ body: Uint8Array;
56
+ }) => Promise<{
57
+ status: number;
58
+ text(): Promise<string>;
59
+ }>;
60
+ export declare function b64urlEncode(buf: Uint8Array): string;
61
+ export declare function b64urlDecode(s: string): Buffer;
62
+ /**
63
+ * Encrypt `plaintext` for one subscription (RFC 8291, `aes128gcm`). `salt` and
64
+ * the application server's ephemeral keypair are random unless given (the test
65
+ * vector seam). Returns the full request body: the RFC 8188 header (salt, record
66
+ * size, key id = the ephemeral public key) followed by the single record.
67
+ */
68
+ export declare function encryptPushPayload(plaintext: Uint8Array, uaPublicB64: string, authSecretB64: string, opts?: {
69
+ salt?: Uint8Array;
70
+ asPrivateKey?: Uint8Array;
71
+ }): Buffer;
72
+ /** A fresh VAPID keypair. */
73
+ export declare function generateVapidKeys(): VapidKeys;
74
+ /**
75
+ * The `Authorization` header value for a push to `endpoint`: `vapid t=<JWT>,
76
+ * k=<public key>`, the JWT signed ES256 with `aud` = the endpoint's origin,
77
+ * `exp` = now + 12 h (the RFC's 24 h ceiling, with margin), `sub` = `subject`.
78
+ */
79
+ export declare function vapidAuthorization(endpoint: string, keys: VapidKeys, subject: string, nowMs?: number): string;
80
+ /**
81
+ * The VAPID `sub` claim: the configured `assistantWebPush.subject` when it is a
82
+ * `mailto:` or http(s) URL, else the configured `publicUrl`, else the project's
83
+ * homepage. Decision: a push service only uses it as a contact for the sender
84
+ * operator, so a fallback that always validates beats refusing to push; the
85
+ * subject is not a secret and changing it needs no new keys.
86
+ */
87
+ export declare function resolveVapidSubject(config: {
88
+ subject?: unknown;
89
+ publicUrl?: unknown;
90
+ }): string;
91
+ /** Validate a POSTed subscription; the error names what is wrong. */
92
+ export declare function validateSubscription(input: unknown): {
93
+ ok: true;
94
+ subscription: PushSubscriptionRecord;
95
+ } | {
96
+ ok: false;
97
+ error: string;
98
+ };
99
+ export interface WebPushStoreOptions {
100
+ stateDir: string;
101
+ /** The VAPID `sub` claim (see `resolveVapidSubject`). */
102
+ subject: string;
103
+ fetch?: PushFetch;
104
+ /** Push TTL in seconds (how long the push service keeps an undelivered message). Default 24 h. */
105
+ ttlSeconds?: number;
106
+ }
107
+ /** One send's outcome per subscription. */
108
+ export interface PushSendOutcome {
109
+ endpoint: string;
110
+ status: number | null;
111
+ /** True when the push service accepted it (2xx). */
112
+ delivered: boolean;
113
+ /** True when the subscription was removed (404 / 410). */
114
+ pruned: boolean;
115
+ error?: string;
116
+ }
117
+ /**
118
+ * The Web Push channel: VAPID keys, the subscription store and the sender. Also
119
+ * what the token-gated `/push/*` routes drive (index.ts).
120
+ */
121
+ export declare class WebPushChannel implements AssistantChannel {
122
+ readonly name = "webpush";
123
+ private readonly vapidPath;
124
+ private readonly subscriptionsPath;
125
+ private readonly subject;
126
+ private readonly fetchImpl;
127
+ private readonly ttlSeconds;
128
+ private keys;
129
+ /** Serialises read-modify-write of the subscription file. */
130
+ private writes;
131
+ constructor(opts: WebPushStoreOptions);
132
+ start(): void;
133
+ stop(): void;
134
+ /** The public key IF it was already generated (status); never generates. */
135
+ existingPublicKey(): string | null;
136
+ /** The public key, generating (and persisting, 0600) the keypair on first use. */
137
+ publicKey(): string;
138
+ subscriptions(): PushSubscriptionRecord[];
139
+ isSubscribed(endpoint: string): boolean;
140
+ /** Add or replace (same endpoint) a subscription. */
141
+ subscribe(sub: PushSubscriptionRecord): Promise<number>;
142
+ /** Remove a subscription; resolves true when it was registered. */
143
+ unsubscribe(endpoint: string): Promise<boolean>;
144
+ /**
145
+ * Send one push to EVERY subscription, in parallel. A 404 / 410 prunes that
146
+ * subscription (the browser dropped it); any other failure is logged and kept.
147
+ */
148
+ send(payload: DeclarativePushPayload): Promise<PushSendOutcome[]>;
149
+ /**
150
+ * The channel's `notify`: one declarative push whose tap opens
151
+ * `/#<sessionId>`. The title is prefixed with the source (decision, so the
152
+ * device shows WHO notified, like Telegram's `🔔 <source>: <title>`).
153
+ */
154
+ notify(n: ChannelNotification): Promise<ChannelNotifyResult>;
155
+ private sendOne;
156
+ private readKeys;
157
+ /**
158
+ * The keypair, generated once. An unreadable existing file is NOT replaced
159
+ * (every subscription is bound to the old public key, so a silent rotation
160
+ * would break every device): it throws, naming the file to fix or remove.
161
+ */
162
+ private ensureKeys;
163
+ private mutate;
164
+ }
165
+ /** The declarative payload for a notification (the service worker's `DeclarativePushNotification`). */
166
+ export declare function webPushPayload(n: ChannelNotification): DeclarativePushPayload;
167
+ //# sourceMappingURL=web-push.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"web-push.d.ts","sourceRoot":"","sources":["../src/web-push.ts"],"names":[],"mappings":"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"}