@gjsify/system-accounts 0.55.0 → 0.57.0

package/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export { createSystemAccounts } from './system-accounts.js';
+export { isUnavailable } from './no-account-store.js';
+export type { Account, AccountCapabilities, AccountService, ConnectionSecurity, CredentialKind, CredentialPurpose, Credentials, MailSettings, OAuth2Credentials, PasswordCredentials, ServerSettings, SystemAccounts, Unavailable, UnavailableReason, } from './types.js';

package/lib/types/mapping.d.ts

@@ -0,0 +1,44 @@
+import type { AccountService, ConnectionSecurity, CredentialPurpose, MailSettings, ServerSettings } from './types.js';
+export interface HostPort {
+    readonly host: string;
+    readonly port?: number;
+}
+/**
+ * Split `host`, `host:port` and `[v6]:port`. A bare IPv6 literal has several colons and no
+ * port. A port outside 1..65535 is dropped rather than guessed, so the caller falls back to
+ * the protocol default instead of dialling port 0.
+ */
+export declare function splitHostPort(raw: string): HostPort;
+/**
+ * The two flags an account store keeps for transport security. When neither is set the
+ * port still tells: 993/465 is TLS from the first byte, which some stores leave unflagged.
+ */
+export declare function securityFromFlags(protocol: CredentialPurpose, useSsl: boolean, useTls: boolean, explicitPort?: number): ConnectionSecurity;
+export interface ServerFields {
+    readonly host: string;
+    readonly userName: string;
+    readonly useSsl: boolean;
+    readonly useTls: boolean;
+    /** False for a server that takes no login: the user name is then not reported. */
+    readonly authenticate: boolean;
+}
+/** `undefined` when the account names no host. */
+export declare function serverSettingsFrom(protocol: CredentialPurpose, fields: ServerFields): ServerSettings | undefined;
+export interface MailFields {
+    readonly emailAddress: string;
+    readonly name: string;
+    readonly imapSupported: boolean;
+    readonly imap: Omit<ServerFields, 'authenticate'>;
+    readonly smtpSupported: boolean;
+    readonly smtp: ServerFields;
+}
+/** `undefined` when the account has neither an IMAP nor an SMTP server. */
+export declare function mailSettingsFrom(fields: MailFields): MailSettings | undefined;
+/** The services an account is set up for and the user has not switched off. */
+export declare function enabledServices(present: Readonly<Record<AccountService, boolean>>, disabled: Readonly<Record<AccountService, boolean>>): AccountService[];
+/**
+ * The secret ids to try, in order. The store keeps the IMAP and the SMTP password under
+ * their own ids; the bare ids are what older account types used. SMTP falls back to the
+ * IMAP password because one login often serves both and the store keeps it once.
+ */
+export declare function passwordIds(purpose: CredentialPurpose): readonly string[];

package/lib/types/mapping.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/no-account-store.d.ts

@@ -0,0 +1,4 @@
+import type { SystemAccounts, Unavailable } from './types.js';
+/** The answer of a host with no account store: nothing is listed, every question gets a reason. */
+export declare const noAccountStore: SystemAccounts;
+export declare function isUnavailable<T extends object>(answer: T | Unavailable): answer is Unavailable;

package/lib/types/no-account-store.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/types.d.ts

@@ -0,0 +1,78 @@
+export type AccountService = 'mail' | 'calendar' | 'contacts' | 'files';
+/** Which login a credential is for. IMAP and SMTP can hold different secrets. */
+export type CredentialPurpose = 'imap' | 'smtp';
+export type CredentialKind = 'password' | 'oauth2';
+/** `tls` is TLS from the first byte, `starttls` upgrades a plain connection, `none` stays plain. */
+export type ConnectionSecurity = 'tls' | 'starttls' | 'none';
+export interface Account {
+    /** Stable for one account on one host; opaque to the caller. */
+    readonly id: string;
+    /** The store's provider key, e.g. `google` or `imap_smtp`. For display and diagnostics, not for branching. */
+    readonly provider: string;
+    readonly providerName: string;
+    /** What the user logs in as, usually the mail address. */
+    readonly identity: string;
+    /** The name the system shows for the account. */
+    readonly label: string;
+    /** The services the account is set up for AND the user has not switched off. */
+    readonly services: readonly AccountService[];
+}
+export interface ServerSettings {
+    readonly host: string;
+    readonly port: number;
+    readonly security: ConnectionSecurity;
+    /** Absent when the server takes no login (an SMTP relay without authentication). */
+    readonly username?: string;
+}
+export interface MailSettings {
+    readonly sender: {
+        readonly address: string;
+        readonly name?: string;
+    };
+    /** Absent when the account has no IMAP server configured. */
+    readonly imap?: ServerSettings;
+    /** Absent when the account has no SMTP server configured. */
+    readonly smtp?: ServerSettings;
+}
+export interface PasswordCredentials {
+    readonly kind: 'password';
+    readonly secret: string;
+}
+export interface OAuth2Credentials {
+    readonly kind: 'oauth2';
+    /** An access token, valid until `expiresAt`. Ask again afterwards; never store it. */
+    readonly token: string;
+    /** Milliseconds since the epoch. */
+    readonly expiresAt: number;
+}
+/**
+ * Why a question got no answer. A missing capability is a value, never an exception
+ * (ADR 0095), so callers branch on this instead of wrapping every call in try/catch.
+ */
+export type UnavailableReason = 
+/** The host has no account store, or it cannot be reached. */
+'no-account-store' | 'unknown-account'
+/** The account exists but is not set up for what was asked, e.g. no mail server. */
+ | 'not-supported'
+/** The store would not hand the secret out: locked, cancelled, or none stored. */
+ | 'credentials-unavailable';
+export interface Unavailable {
+    readonly kind: 'unavailable';
+    readonly reason: UnavailableReason;
+}
+export type Credentials = PasswordCredentials | OAuth2Credentials | Unavailable;
+export interface AccountCapabilities {
+    /** Services `listAccounts` can report. Empty: this host has no account store. */
+    readonly services: readonly AccountService[];
+    /** Credential kinds `getCredentials` can hand out. Empty: accounts are listed but no secret is given. */
+    readonly credentials: readonly CredentialKind[];
+}
+export interface SystemAccounts {
+    /** What THIS host can answer. Synchronous and cheap: decided when the driver is created. */
+    capabilities(): AccountCapabilities;
+    /** Accounts, optionally only those set up for `service`. Empty when the store cannot be reached. */
+    listAccounts(service?: AccountService): Promise<Account[]>;
+    getMailSettings(account: Account): Promise<MailSettings | Unavailable>;
+    /** The caller owns the result: it is never logged, cached or put in an error by this package. */
+    getCredentials(account: Account, purpose: CredentialPurpose): Promise<Credentials>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/system-accounts",
-    "version": "0.55.0",
+    "version": "0.57.0",
     "description": "The accounts a user already set up on their system: find them, read their mail server settings, get credentials. GNOME Online Accounts on Linux.",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -47,8 +47,8 @@
         "@girs/goa-1.0": "5.4.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.55.0",
-        "@gjsify/unit": "^0.55.0",
+        "@gjsify/cli": "^0.57.0",
+        "@gjsify/unit": "^0.57.0",
         "typescript": "^6.0.3"
     },
     "license": "MIT",