@better-forge/contracts 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BetterStatusPage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @better-forge/contracts
+
+Browser-safe types, core translations and a storage wrapper that never throws shared by the other modules.
+
+Status: skeleton. Depends on: nothing.

package/dist/apiToken.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What an API token may do. A token carries a list of permissions instead of a role: each one names a part of the
+ * admin API and whether it may be read (`:read`) or changed (`:write`, which includes reading). `vault:use` is a
+ * separate permission to use secrets from a vault in a configuration.
+ */
+export interface TokenResource {
+    key: string;
+    label: string;
+    description: string;
+    /** `read` only for parts that cannot be changed through the API. */
+    levels: readonly ('read' | 'write')[];
+}
+/** Lets a token set, change or test a configuration that reads a secret from a vault. */
+export declare const VAULT_USE_SCOPE = "vault:use";
+export interface TokenPreset {
+    label: string;
+    description: string;
+    scopes: readonly string[];
+}
+/**
+ * The permissions a token needs for a request: `<resource>:read` for GET and HEAD, `<resource>:write` for anything
+ * else. The vault catalogue is the one part with a single permission.
+ */
+export declare function requiredScope(resource: string, method: string): string;
+/** Whether a token with `granted` may do what needs `required`. Writing a part includes reading it. */
+export declare function tokenAllows(granted: readonly string[], required: string): boolean;
+/**
+ * A clean list of permissions out of `known` (reading added wherever writing is granted, ordered as `known` is), or
+ * null if one is unknown or none is given.
+ */
+export declare function normalizeScopes(input: unknown, known: readonly string[]): string[] | null;
+//# sourceMappingURL=apiToken.d.ts.map

package/dist/apiToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiToken.d.ts","sourceRoot":"","sources":["../src/apiToken.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAA;CACtC;AAED,yFAAyF;AACzF,eAAO,MAAM,eAAe,cAAc,CAAA;AAE1C,MAAM,WAAW,WAAW;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AAE9F;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGjF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAKzF"}

package/dist/apiToken.js

@@ -0,0 +1,36 @@
+/**
+ * What an API token may do. A token carries a list of permissions instead of a role: each one names a part of the
+ * admin API and whether it may be read (`:read`) or changed (`:write`, which includes reading). `vault:use` is a
+ * separate permission to use secrets from a vault in a configuration.
+ */
+/** Lets a token set, change or test a configuration that reads a secret from a vault. */
+export const VAULT_USE_SCOPE = 'vault:use';
+/**
+ * The permissions a token needs for a request: `<resource>:read` for GET and HEAD, `<resource>:write` for anything
+ * else. The vault catalogue is the one part with a single permission.
+ */
+export function requiredScope(resource, method) {
+    if (resource === 'vault')
+        return VAULT_USE_SCOPE;
+    return `${resource}:${method === 'GET' || method === 'HEAD' ? 'read' : 'write'}`;
+}
+/** Whether a token with `granted` may do what needs `required`. Writing a part includes reading it. */
+export function tokenAllows(granted, required) {
+    if (granted.includes(required))
+        return true;
+    return required.endsWith(':read') && granted.includes(`${required.slice(0, -':read'.length)}:write`);
+}
+/**
+ * A clean list of permissions out of `known` (reading added wherever writing is granted, ordered as `known` is), or
+ * null if one is unknown or none is given.
+ */
+export function normalizeScopes(input, known) {
+    if (!Array.isArray(input) || input.length === 0 || !input.every((scope) => typeof scope === 'string' && known.includes(scope)))
+        return null;
+    const scopes = new Set(input);
+    for (const scope of input)
+        if (scope.endsWith(':write') && known.includes(`${scope.slice(0, -':write'.length)}:read`))
+            scopes.add(`${scope.slice(0, -':write'.length)}:read`);
+    return known.filter((scope) => scopes.has(scope));
+}
+//# sourceMappingURL=apiToken.js.map

package/dist/apiToken.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiToken.js","sourceRoot":"","sources":["../src/apiToken.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,yFAAyF;AACzF,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAA;AAI1C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,MAAc;IAC5D,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,eAAe,CAAA;IAChD,OAAO,GAAG,QAAQ,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAClF,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,WAAW,CAAC,OAA0B,EAAE,QAAgB;IACtE,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3C,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;AACtG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,KAAwB;IACtE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3I,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,KAAiB,CAAC,CAAA;IACjD,KAAK,MAAM,KAAK,IAAI,KAAiB;QAAE,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACzL,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA;AACnD,CAAC"}

package/dist/audit.d.ts

@@ -0,0 +1,22 @@
+/** `allow` records a successful sign-in; `deny` a refused action, such as a sign-in with a wrong password. */
+export type AuditAction = 'create' | 'update' | 'delete' | 'allow' | 'deny';
+/** The kinds of object the shared modules write to the audit log; an app adds its own. */
+export type KitAuditEntityType = 'notification_channel' | 'smtp_settings' | 'vault' | 'vault_secret' | 'user' | 'api_token' | 'oidc_settings'
+/** Security changes on a user account: password, two-factor, SSO link. */
+ | 'user-security'
+/** A configuration import; the entities it changed have entries of their own. */
+ | 'config' | 'backup' | 'backup-config' | 'notification_delivery'
+/** Every sign-in attempt, with a password or SSO; `diff.method` says which. */
+ | 'sign_in';
+export interface AuditLogEntry<EntityType extends string = string> {
+    id: number;
+    userId: number;
+    userEmail: string;
+    action: AuditAction;
+    entityType: EntityType;
+    entityId: string | null;
+    entityName: string;
+    diff: Record<string, unknown> | null;
+    timestamp: number;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;AAE3E,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAC1B,sBAAsB,GACtB,eAAe,GACf,OAAO,GACP,cAAc,GACd,MAAM,GACN,WAAW,GACX,eAAe;AACjB,0EAA0E;GACxE,eAAe;AACjB,iFAAiF;GAC/E,QAAQ,GACR,QAAQ,GACR,eAAe,GACf,uBAAuB;AACzB,+EAA+E;GAC7E,SAAS,CAAA;AAEb,MAAM,WAAW,aAAa,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM;IAC/D,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACpC,SAAS,EAAE,MAAM,CAAA;CAClB"}

package/dist/audit.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './vault.js';
+export * from './notification.js';
+export * from './apiToken.js';
+export * from './audit.js';
+export * from './locale.js';
+export * from './safeStorage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './vault.js';
+export * from './notification.js';
+export * from './apiToken.js';
+export * from './audit.js';
+export * from './locale.js';
+export * from './safeStorage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA"}

package/dist/locale.d.ts

@@ -0,0 +1,15 @@
+export interface Locale<Key extends string = string> {
+    code: string;
+    name: string;
+    isDefault: number;
+    translations: Partial<Record<Key, string>>;
+    updatedAt: number;
+}
+export interface LocaleSummary {
+    code: string;
+    name: string;
+    isDefault?: number;
+}
+/** The language part of a locale code: "pl-PL" and "pl_PL" are both "pl". */
+export declare function baseLanguage(code: string): string;
+//# sourceMappingURL=locale.d.ts.map

package/dist/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/locale.js

@@ -0,0 +1,5 @@
+/** The language part of a locale code: "pl-PL" and "pl_PL" are both "pl". */
+export function baseLanguage(code) {
+    return code.trim().toLowerCase().split(/[-_]/)[0] ?? '';
+}
+//# sourceMappingURL=locale.js.map

package/dist/locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.js","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAcA,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;AACzD,CAAC"}

package/dist/notification.d.ts

@@ -0,0 +1,94 @@
+import type { VaultRef } from './vault.js';
+export type NotificationChannelType = 'email' | 'webhook' | 'discord' | 'teams' | 'slack' | 'telegram' | 'ntfy' | 'pushover';
+export interface EmailNotificationConfig {
+    to: string;
+    subject: string;
+    body: string;
+}
+export interface WebhookNotificationConfig {
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface DiscordNotificationConfig {
+    webhookUrl: string;
+    username?: string;
+    avatarUrl?: string;
+    content?: string;
+}
+export interface TeamsNotificationConfig {
+    webhookUrl: string;
+    summary?: string;
+}
+export interface SlackNotificationConfig {
+    webhookUrl: string;
+    text?: string;
+}
+export interface TelegramNotificationConfig {
+    /** Direct token; the API only ever returns it masked. Ignored when `vault` is set. */
+    botToken?: string;
+    /** Vault secret holding the token: a `value` secret. */
+    vault?: VaultRef;
+    chatId: string;
+    text?: string;
+}
+export interface NtfyNotificationConfig {
+    /** Server root; ntfy.sh when omitted. */
+    serverUrl?: string;
+    topic: string;
+    /** Access token of a protected topic; the API only ever returns it masked. Ignored when `vault` is set. */
+    accessToken?: string;
+    /** Vault secret holding the access token: a `value` secret. */
+    vault?: VaultRef;
+    text?: string;
+}
+export interface PushoverNotificationConfig {
+    /** Application token; the API only ever returns it masked. Ignored when `vault` is set. */
+    appToken?: string;
+    /** Vault secret holding the application token: a `value` secret. */
+    vault?: VaultRef;
+    /** User or group key that receives the messages. */
+    userKey: string;
+    text?: string;
+}
+/** The wording a channel has for one kind of event, by event type: only the message fields of its type (subject, body, text...). */
+export interface ChannelEventOverrides {
+    eventOverrides?: Record<string, Record<string, string>>;
+}
+export type NotificationChannelConfig = (EmailNotificationConfig | WebhookNotificationConfig | DiscordNotificationConfig | TeamsNotificationConfig | SlackNotificationConfig | TelegramNotificationConfig | NtfyNotificationConfig | PushoverNotificationConfig) & ChannelEventOverrides;
+/** Quiet hours silence a channel during a recurring local-time window. */
+export interface QuietHoursPolicy {
+    enabled: boolean;
+    /** Local start of the quiet window, `HH:MM` (24h). */
+    start: string;
+    /** Local end of the quiet window, `HH:MM`. When <= start the window wraps past midnight. */
+    end: string;
+    /** IANA timezone the window is expressed in, e.g. `Europe/Warsaw`. */
+    timezone: string;
+    /** `defer` holds notifications until the window ends; `suppress` drops them. */
+    mode: 'defer' | 'suppress';
+}
+export type NotificationSuppressionReason = 'quiet-hours' | 'throttled' | 'grouped';
+export interface SmtpSettings {
+    host: string;
+    port: number;
+    secure: number;
+    user: string;
+    password: string;
+    fromAddress: string;
+    fromName: string;
+    vault?: VaultRef | null;
+    updatedAt: number;
+}
+export type NotificationDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'suppressed';
+export interface NotificationDeliveryAttempt {
+    id: number;
+    deliveryId: number;
+    attemptNumber: number;
+    status: 'delivered' | 'failed';
+    error: string | null;
+    startedAt: number;
+    completedAt: number;
+}
+//# sourceMappingURL=notification.d.ts.map

package/dist/notification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.d.ts","sourceRoot":"","sources":["../src/notification.ts"],"names":[],"mappings":"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"}

package/dist/notification.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=notification.js.map

package/dist/notification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.js","sourceRoot":"","sources":["../src/notification.ts"],"names":[],"mappings":""}

package/dist/safeStorage.d.ts

@@ -0,0 +1,9 @@
+/** Browser storage that never throws: a blocked or full storage reads as empty and drops writes. */
+export interface SafeStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+export declare const safeLocalStorage: SafeStorage;
+export declare const safeSessionStorage: SafeStorage;
+//# sourceMappingURL=safeStorage.d.ts.map

package/dist/safeStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeStorage.d.ts","sourceRoot":"","sources":["../src/safeStorage.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAUD,eAAO,MAAM,gBAAgB,aAA2B,CAAA;AACxD,eAAO,MAAM,kBAAkB,aAA6B,CAAA"}

package/dist/safeStorage.js

@@ -0,0 +1,21 @@
+function safe(area) {
+    return {
+        get(key) { try {
+            return area().getItem(key);
+        }
+        catch {
+            return null;
+        } },
+        set(key, value) { try {
+            area().setItem(key, value);
+        }
+        catch { /* storage unavailable: the value lasts for this page only */ } },
+        remove(key) { try {
+            area().removeItem(key);
+        }
+        catch { /* storage unavailable: nothing to remove */ } },
+    };
+}
+export const safeLocalStorage = safe(() => localStorage);
+export const safeSessionStorage = safe(() => sessionStorage);
+//# sourceMappingURL=safeStorage.js.map

package/dist/safeStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeStorage.js","sourceRoot":"","sources":["../src/safeStorage.ts"],"names":[],"mappings":"AAOA,SAAS,IAAI,CAAC,IAAmB;IAC/B,OAAO;QACL,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC;YAAC,OAAO,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,IAAI,CAAA;QAAC,CAAC,CAAC,CAAC;QACrE,GAAG,CAAC,GAAG,EAAE,KAAK,IAAI,IAAI,CAAC;YAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,6DAA6D,CAAC,CAAC,CAAC,CAAC;QAC9H,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC;YAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,CAAC;KACtG,CAAA;AACH,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAA;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,CAAA"}

package/dist/vault.d.ts

@@ -0,0 +1,8 @@
+/** Reference to a vault secret, with optional field mapping for json-type secrets */
+export interface VaultRef {
+    vaultId: number;
+    secretId: number;
+    /** Only for json-type secrets: maps our field names to JSON object keys */
+    fieldMapping?: Record<string, string>;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC"}

package/dist/vault.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,43 @@
-{
-  "name": "@better-forge/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@better-forge/contracts",
+  "version": "0.1.0",
+  "description": "Browser-safe types, core translations and a storage wrapper that never throws.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/contracts#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/apiToken.ts

@@ -0,0 +1,44 @@
+/**
+ * What an API token may do. A token carries a list of permissions instead of a role: each one names a part of the
+ * admin API and whether it may be read (`:read`) or changed (`:write`, which includes reading). `vault:use` is a
+ * separate permission to use secrets from a vault in a configuration.
+ */
+
+export interface TokenResource {
+  key: string
+  label: string
+  description: string
+  /** `read` only for parts that cannot be changed through the API. */
+  levels: readonly ('read' | 'write')[]
+}
+
+/** Lets a token set, change or test a configuration that reads a secret from a vault. */
+export const VAULT_USE_SCOPE = 'vault:use'
+
+export interface TokenPreset { label: string; description: string; scopes: readonly string[] }
+
+/**
+ * The permissions a token needs for a request: `<resource>:read` for GET and HEAD, `<resource>:write` for anything
+ * else. The vault catalogue is the one part with a single permission.
+ */
+export function requiredScope(resource: string, method: string): string {
+  if (resource === 'vault') return VAULT_USE_SCOPE
+  return `${resource}:${method === 'GET' || method === 'HEAD' ? 'read' : 'write'}`
+}
+
+/** Whether a token with `granted` may do what needs `required`. Writing a part includes reading it. */
+export function tokenAllows(granted: readonly string[], required: string): boolean {
+  if (granted.includes(required)) return true
+  return required.endsWith(':read') && granted.includes(`${required.slice(0, -':read'.length)}:write`)
+}
+
+/**
+ * A clean list of permissions out of `known` (reading added wherever writing is granted, ordered as `known` is), or
+ * null if one is unknown or none is given.
+ */
+export function normalizeScopes(input: unknown, known: readonly string[]): string[] | null {
+  if (!Array.isArray(input) || input.length === 0 || !input.every((scope) => typeof scope === 'string' && known.includes(scope))) return null
+  const scopes = new Set<string>(input as string[])
+  for (const scope of input as string[]) if (scope.endsWith(':write') && known.includes(`${scope.slice(0, -':write'.length)}:read`)) scopes.add(`${scope.slice(0, -':write'.length)}:read`)
+  return known.filter((scope) => scopes.has(scope))
+}

package/src/audit.ts

@@ -0,0 +1,33 @@
+/** `allow` records a successful sign-in; `deny` a refused action, such as a sign-in with a wrong password. */
+export type AuditAction = 'create' | 'update' | 'delete' | 'allow' | 'deny'
+
+/** The kinds of object the shared modules write to the audit log; an app adds its own. */
+export type KitAuditEntityType =
+  | 'notification_channel'
+  | 'smtp_settings'
+  | 'vault'
+  | 'vault_secret'
+  | 'user'
+  | 'api_token'
+  | 'oidc_settings'
+  /** Security changes on a user account: password, two-factor, SSO link. */
+  | 'user-security'
+  /** A configuration import; the entities it changed have entries of their own. */
+  | 'config'
+  | 'backup'
+  | 'backup-config'
+  | 'notification_delivery'
+  /** Every sign-in attempt, with a password or SSO; `diff.method` says which. */
+  | 'sign_in'
+
+export interface AuditLogEntry<EntityType extends string = string> {
+  id: number
+  userId: number
+  userEmail: string
+  action: AuditAction
+  entityType: EntityType
+  entityId: string | null
+  entityName: string
+  diff: Record<string, unknown> | null
+  timestamp: number
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './vault.js'
+export * from './notification.js'
+export * from './apiToken.js'
+export * from './audit.js'
+export * from './locale.js'
+export * from './safeStorage.js'

package/src/locale.ts

@@ -0,0 +1,18 @@
+export interface Locale<Key extends string = string> {
+  code: string
+  name: string
+  isDefault: number
+  translations: Partial<Record<Key, string>>
+  updatedAt: number
+}
+
+export interface LocaleSummary {
+  code: string
+  name: string
+  isDefault?: number
+}
+
+/** The language part of a locale code: "pl-PL" and "pl_PL" are both "pl". */
+export function baseLanguage(code: string): string {
+  return code.trim().toLowerCase().split(/[-_]/)[0] ?? ''
+}

package/src/notification.ts

@@ -0,0 +1,110 @@
+import type { VaultRef } from './vault.js'
+
+export type NotificationChannelType = 'email' | 'webhook' | 'discord' | 'teams' | 'slack' | 'telegram' | 'ntfy' | 'pushover'
+
+export interface EmailNotificationConfig {
+  to: string
+  subject: string
+  body: string
+}
+
+export interface WebhookNotificationConfig {
+  url: string
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH'
+  headers?: Record<string, string>
+  body?: string
+}
+
+export interface DiscordNotificationConfig {
+  webhookUrl: string
+  username?: string
+  avatarUrl?: string
+  content?: string
+}
+
+export interface TeamsNotificationConfig {
+  webhookUrl: string
+  summary?: string
+}
+
+export interface SlackNotificationConfig {
+  webhookUrl: string
+  text?: string
+}
+
+export interface TelegramNotificationConfig {
+  /** Direct token; the API only ever returns it masked. Ignored when `vault` is set. */
+  botToken?: string
+  /** Vault secret holding the token: a `value` secret. */
+  vault?: VaultRef
+  chatId: string
+  text?: string
+}
+
+export interface NtfyNotificationConfig {
+  /** Server root; ntfy.sh when omitted. */
+  serverUrl?: string
+  topic: string
+  /** Access token of a protected topic; the API only ever returns it masked. Ignored when `vault` is set. */
+  accessToken?: string
+  /** Vault secret holding the access token: a `value` secret. */
+  vault?: VaultRef
+  text?: string
+}
+
+export interface PushoverNotificationConfig {
+  /** Application token; the API only ever returns it masked. Ignored when `vault` is set. */
+  appToken?: string
+  /** Vault secret holding the application token: a `value` secret. */
+  vault?: VaultRef
+  /** User or group key that receives the messages. */
+  userKey: string
+  text?: string
+}
+
+/** The wording a channel has for one kind of event, by event type: only the message fields of its type (subject, body, text...). */
+export interface ChannelEventOverrides {
+  eventOverrides?: Record<string, Record<string, string>>
+}
+
+export type NotificationChannelConfig = (EmailNotificationConfig | WebhookNotificationConfig | DiscordNotificationConfig | TeamsNotificationConfig | SlackNotificationConfig | TelegramNotificationConfig | NtfyNotificationConfig | PushoverNotificationConfig) & ChannelEventOverrides
+
+/** Quiet hours silence a channel during a recurring local-time window. */
+export interface QuietHoursPolicy {
+  enabled: boolean
+  /** Local start of the quiet window, `HH:MM` (24h). */
+  start: string
+  /** Local end of the quiet window, `HH:MM`. When <= start the window wraps past midnight. */
+  end: string
+  /** IANA timezone the window is expressed in, e.g. `Europe/Warsaw`. */
+  timezone: string
+  /** `defer` holds notifications until the window ends; `suppress` drops them. */
+  mode: 'defer' | 'suppress'
+}
+
+export type NotificationSuppressionReason = 'quiet-hours' | 'throttled' | 'grouped'
+
+
+export interface SmtpSettings {
+  host: string
+  port: number
+  secure: number
+  user: string
+  password: string
+  fromAddress: string
+  fromName: string
+  vault?: VaultRef | null
+  updatedAt: number
+}
+
+export type NotificationDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'suppressed'
+
+export interface NotificationDeliveryAttempt {
+  id: number
+  deliveryId: number
+  attemptNumber: number
+  status: 'delivered' | 'failed'
+  error: string | null
+  startedAt: number
+  completedAt: number
+}

package/src/safeStorage.ts

@@ -0,0 +1,17 @@
+/** Browser storage that never throws: a blocked or full storage reads as empty and drops writes. */
+export interface SafeStorage {
+  get(key: string): string | null
+  set(key: string, value: string): void
+  remove(key: string): void
+}
+
+function safe(area: () => Storage): SafeStorage {
+  return {
+    get(key) { try { return area().getItem(key) } catch { return null } },
+    set(key, value) { try { area().setItem(key, value) } catch { /* storage unavailable: the value lasts for this page only */ } },
+    remove(key) { try { area().removeItem(key) } catch { /* storage unavailable: nothing to remove */ } },
+  }
+}
+
+export const safeLocalStorage = safe(() => localStorage)
+export const safeSessionStorage = safe(() => sessionStorage)

package/src/vault.ts

@@ -0,0 +1,7 @@
+/** Reference to a vault secret, with optional field mapping for json-type secrets */
+export interface VaultRef {
+  vaultId: number
+  secretId: number
+  /** Only for json-type secrets: maps our field names to JSON object keys */
+  fieldMapping?: Record<string, string>
+}