@ts-cloud/core 0.9.4 → 0.11.0

package/dist/app-mail.d.ts

@@ -0,0 +1,130 @@
+import type { CloudConfig, EnvironmentType, MailServiceConfig, MailServiceMode } from './types';
+/**
+ * The one place that decides what "mail" means for an environment.
+ *
+ * `services.mail` is deliberately allowed to be `true`, because the useful
+ * declaration is "this project sends email" and not "this project runs an MTA
+ * on 25 with DKIM keys for two domains and a smarthost". Everything after that
+ * follows from the environment: production wants a real server, a preview box
+ * wants a trap. Both are the same binary, which is the point - see
+ * {@link MailServiceMode}.
+ *
+ * The provisioner, the firewall, the DNS planner and the `.env` writer all
+ * resolve through here so they cannot disagree about which ports are open,
+ * which hostname is announced, or where the webmail UI is. That mattered
+ * immediately: a catcher whose SMTP port the `.env` said was 1025 and whose
+ * firewall rule said 25 is a box where mail silently goes nowhere.
+ */
+/** Everything about the mail service, with nothing left to infer. */
+export interface ResolvedMailService {
+    /** Whether mail is provisioned at all. */
+    enabled: boolean;
+    /** Real MTA or local trap. */
+    mode: MailServiceMode;
+    /** Pinned version, or `undefined` for the latest release. */
+    version?: string;
+    /** The FQDN the server announces and signs as. */
+    hostname: string;
+    /** Every domain delivered to mailboxes here, `hostname`'s parent included. */
+    domains: string[];
+    /** Resolved listening ports; a port that is off is absent. */
+    ports: ResolvedMailPorts;
+    /** TLS, resolved. `acme` implies the server obtains its own certificate. */
+    tls: {
+        enabled: boolean;
+        acme: boolean;
+        certPath?: string;
+        keyPath?: string;
+        requireForAuth: boolean;
+        acmeEmail?: string;
+    };
+    /** DKIM, resolved. Off means the server signs nothing. */
+    dkim: {
+        enabled: boolean;
+        selector: string;
+        rotate: boolean;
+        rotateIntervalDays: number;
+    };
+    /** Webmail UI, resolved. */
+    webmail: {
+        enabled: boolean;
+        port: number;
+        domain?: string;
+    };
+    /** How outbound mail leaves. */
+    delivery: 'direct' | 'ses' | 'none';
+    /** SES region for `delivery: 'ses'`. */
+    sesRegion: string;
+    /** Mailboxes created on provision. */
+    accounts: Array<{
+        address: string;
+        password: string;
+    }>;
+    /** Where mailboxes, the database and the DKIM keys live. */
+    storagePath: string;
+    /** Largest accepted message, in bytes. */
+    maxMessageSize: number;
+    /** Inbound spam handling, resolved. */
+    spam: {
+        enabled: boolean;
+        enforce: boolean;
+        junkScore: number;
+        rejectScore: number;
+        dnsbl: boolean;
+        greylist: boolean;
+    };
+    /** Where received mail is POSTed, when configured. */
+    webhookUrl?: string;
+    /** Whether the mail ports face the internet. */
+    expose: boolean;
+    /** The address the listeners bind to, which follows from {@link expose}. */
+    bindAddress: string;
+}
+/** Resolved ports. A protocol this mode does not serve is absent, not zero. */
+export interface ResolvedMailPorts {
+    smtp: number;
+    submission?: number;
+    submissions?: number;
+    imap?: number;
+    imaps?: number;
+    webmail: number;
+    managesieve?: number;
+}
+/** Whether a `services.mail` declaration asks for anything at all. */
+export declare function mailEnabled(value: boolean | MailServiceConfig | undefined): boolean;
+export interface ResolveMailOptions {
+    /** Which environment is being provisioned, e.g. `'production'`. */
+    environment?: string;
+    /**
+     * Its type, when the caller already knows it. Otherwise it is read from
+     * `config.environments[environment].type`, and an unknown environment is
+     * treated as non-production - which is the safe direction: the mistake that
+     * costs something is provisioning an open relay, not provisioning a trap.
+     */
+    environmentType?: EnvironmentType;
+}
+/**
+ * Resolve `infrastructure.compute.managedServices.mail` for an environment.
+ *
+ * Returns `enabled: false` (and defaults everywhere else) when mail is not
+ * declared, so callers can read the shape unconditionally instead of guarding
+ * every field.
+ */
+export declare function resolveMailService(config: Pick<CloudConfig, 'project' | 'sites' | 'environments' | 'infrastructure'>, options?: ResolveMailOptions): ResolvedMailService;
+/**
+ * The ports the host firewall has to open for this mail service.
+ *
+ * Empty when mail is not exposed, which is the whole reason this is a function
+ * rather than a list somebody maintains beside the resolver: a catcher's ports
+ * must never end up in an allow list.
+ */
+export declare function mailFirewallPorts(mail: ResolvedMailService): number[];
+/**
+ * `.env` pairs pointing an application at this mail service, in the shape the
+ * Stacks/Laravel families of framework read.
+ *
+ * Merge into a site's `env` so `MAIL_*` is set from the same resolution the
+ * provisioner used. The alternative - a hand-copied `MAIL_PORT` - is the
+ * mistake this whole module exists to make impossible.
+ */
+export declare function buildMailEnv(mail: ResolvedMailService): Record<string, string>;

package/dist/drivers/types.d.ts

@@ -119,6 +119,35 @@ export interface CloudDriver {
     findComputeTargets(options: FindComputeTargetsOptions): Promise<ComputeTarget[]>;
     /** Run a shell script on every target (SSM, SSH, etc.) */
     runRemoteDeploy(options: RunRemoteDeployOptions): Promise<RemoteDeployResult>;
+    /**
+     * Enumerate every resource this driver's credential can see — and therefore,
+     * on providers without per-resource scoping, write to and delete.
+     *
+     * Exists so nothing above the driver has to assume "one all-powerful token"
+     * is the only credential shape. Attaching to another project's box works by
+     * LISTING the provider with the attaching project's own credential, so the
+     * radius is a property of that credential rather than of the config, and only
+     * the driver holding it can report it. A driver whose credential IS narrowly
+     * scoped simply enumerates less, and the same reporting comes out right
+     * without a special case.
+     *
+     * Optional: a driver that cannot enumerate omits it, and callers report no
+     * radius rather than a wrong one.
+     *
+     * @see https://github.com/stacksjs/ts-cloud/issues/169
+     */
+    listReachableResources?(): Promise<ReachableResource[]>;
+}
+/**
+ * One resource a provider credential can reach, reduced to what attribution
+ * needs: a name to print and the labels that say who owns it.
+ *
+ * Deliberately structural and provider-agnostic — a Hetzner server satisfies it
+ * as-is, and another driver can satisfy it without importing anything.
+ */
+export interface ReachableResource {
+    name: string;
+    labels?: Record<string, string>;
 }
 export interface DeploySiteReleaseOptions {
     config: CloudConfig;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './types';
 export * from './state-dir';
 export * from './deployment-mode';
 export * from './app-database';
+export * from './app-mail';
 export * from './drivers';
 export * from './template-builder';
 export { validateTemplate, validateTemplateSize, validateResourceLimits, type ValidationResult, } from './template-validator';