@viaalink/caddy-api-client 0.0.0-stage → 0.10.0

package/dist/index-BijF7qR9.d.ts

@@ -0,0 +1,336 @@
+import * as zod from 'zod';
+
+/**
+ * Provider implements the libdns interfaces for Route53.
+ * By default, the provider loads the AWS configuration from the environment.
+ * To override these values, set the fields in the Provider struct.
+ */
+interface Provider$3 {
+    /**
+     * Region is the AWS Region to use. If not set, it will use AWS_REGION
+     * environment variable.
+     */
+    region?: string;
+    /**
+     * AWSProfile is the AWS Profile to use. If not set, it will use
+     * AWS_PROFILE environment variable.
+     */
+    profile?: string;
+    /**
+     * AccessKeyId is the AWS Access Key ID to use. If not set, it will use
+     * AWS_ACCESS_KEY_ID
+     */
+    access_key_id?: string;
+    /**
+     * SecretAccessKey is the AWS Secret Access Key to use. If not set, it will use
+     * AWS_SECRET_ACCESS_KEY environment variable.
+     */
+    secret_access_key?: string;
+    /**
+     * SessionToken is the AWS Session Token to use. If not set, it will use
+     * AWS_SESSION_TOKEN environment variable.
+     */
+    session_token?: string;
+    /**
+     * MaxRetries is the maximum number of retries to make when a request
+     * fails. If not set, it will use 5 retries.
+     */
+    max_retries?: number;
+    /**
+     * Route53MaxWait is the maximum amount of time to wait for a record
+     * to be propagated within AWS infrastructure. Default is 1 minute.
+     */
+    route53_max_wait?: number;
+    /**
+     * WaitForRoute53Sync if set to true, it will wait for the record to be
+     * propagated within AWS infrastructure before returning. This is not related
+     * to DNS propagation, that could take much longer.
+     */
+    wait_for_route53_sync?: boolean;
+    /**
+     * SkipRoute53SyncOnDelete if set to true, it will skip waiting for Route53
+     * synchronization when deleting records, even if WaitForRoute53Sync is true.
+     * This can speed up bulk delete operations where waiting is not necessary.
+     */
+    skip_route53_sync_on_delete?: boolean;
+    /**
+     * HostedZoneID is the ID of the hosted zone to use. If not set, it will
+     * be discovered from the zone name.
+     * This option should contain only the ID; the "/hostedzone/" prefix
+     * will be added automatically.
+     */
+    hosted_zone_id?: string;
+}
+
+/**
+ * Provider facilitates DNS record manipulation with Porkbun.
+ */
+interface Provider$2 {
+    api_key?: string;
+    api_secret_key?: string;
+}
+
+/**
+ * Provider implements the libdns interfaces for Cloudflare.
+ * TODO: Support retries and handle rate limits.
+ */
+interface Provider$1 {
+    /**
+     * API tokens are used for authentication. Make sure to use
+     * scoped API **tokens**, NOT a global API **key**.
+     */
+    api_token?: string;
+    zone_token?: string;
+}
+
+/**
+ * Provider godaddy dns provider
+ */
+interface Provider {
+    api_token?: string;
+}
+
+/**
+ * caddy-dns plugin types
+ *
+ * Typed `providerConfig` shapes for the `caddy-dns/*` ACME-DNS challenge
+ * provider modules, layered on top of {@link buildAcmeDnsPolicy} in
+ * `src/caddy/acme.ts` (which only builds the wrapper shape and treats
+ * `providerConfig` as an opaque passthrough).
+ *
+ * As of 0.9.0, these types are sourced from real vendored Go source (not
+ * READMEs) via the same tygo pipeline `caddy-security` uses — see
+ * `DEPENDENCIES.md`'s "DNS Provider Plugins" section for exact
+ * versions/commits, and `src/generated/plugins/caddy-dns-*.ts` for the
+ * machine-generated base types this module re-exports/composes.
+ *
+ * @see https://github.com/caddy-dns
+ * @see ../../caddy/acme.ts
+ */
+
+/**
+ * `caddy-dns/digitalocean` provider config.
+ *
+ * Hand-picked rather than re-exported: the generated `Provider` interface
+ * (`src/generated/plugins/caddy-dns-digitalocean.ts`) also carries a
+ * `Client` field — a tygo artifact from Go's anonymous embedding of an
+ * all-unexported `Client` struct, which contributes nothing to the real
+ * JSON output (Go's `encoding/json` never emits an anonymous embed with no
+ * exported fields as a nested key).
+ */
+interface DigitaloceanDnsProviderConfig {
+    auth_token: string;
+}
+/**
+ * `caddy-dns/route53` provider config.
+ *
+ * Real fields span two Go modules: `libdns/route53` (the 10 fields below,
+ * from the generated `Provider` in `caddy-dns-route53-libdns.ts`) plus
+ * `caddy-dns/route53`'s own extra `debug_logging` field (from
+ * `caddy-dns-route53-wrapper.ts`). Composed by hand since tygo can't follow
+ * the wrapper's cross-module pointer embed (`*route53.Provider`)
+ * automatically — see `local/caddy-dns-route53/tygo.yaml`.
+ *
+ * All fields are optional: `caddy-dns/route53` falls back to the AWS Go
+ * SDK v2's own default credential chain (env vars, shared profile, or IAM
+ * role) for anything not explicitly set here.
+ */
+interface Route53DnsProviderConfig extends Provider$3 {
+    /**
+     * Forwards structured events from libdns/route53 (zone resolution,
+     * change submission, sync waits) to Caddy's logger. Emits at Debug level
+     * except for ambiguous-zone warnings — set Caddy's log level to debug to
+     * actually see them.
+     */
+    debug_logging?: boolean;
+}
+/**
+ * Known `dnsProvider` names with a typed builder in this module.
+ */
+declare const KNOWN_ACME_DNS_PROVIDERS: readonly ["porkbun", "cloudflare", "route53", "digitalocean", "godaddy"];
+type KnownAcmeDnsProvider = (typeof KNOWN_ACME_DNS_PROVIDERS)[number];
+/**
+ * Result of building a provider's DNS-01 config: the typed
+ * `providerConfig` to pass through to
+ * {@link buildAcmeDnsPolicy}`.providerConfig`, plus the env var names the
+ * caller should ensure are set (names only — never values).
+ */
+interface AcmeDnsProviderConfigResult {
+    /**
+     * Omitted for providers (e.g. `route53` when called with no explicit
+     * `options`) that resolve credentials outside of `providerConfig`
+     * entirely.
+     */
+    providerConfig?: Record<string, unknown>;
+    /** Env var names referenced by `providerConfig`'s `{env.VAR}` placeholders (or, for `route53`'s default zero-arg call, consumed directly by the AWS SDK's credential chain). */
+    envVars: string[];
+}
+
+/** {@link PorkbunDnsProviderConfig} schema. Exact match to the generated schema. */
+declare const PorkbunDnsProviderConfigSchema: zod.ZodObject<{
+    api_key: zod.ZodOptional<zod.ZodString>;
+    api_secret_key: zod.ZodOptional<zod.ZodString>;
+}, "strip", zod.ZodTypeAny, {
+    api_key?: string | undefined;
+    api_secret_key?: string | undefined;
+}, {
+    api_key?: string | undefined;
+    api_secret_key?: string | undefined;
+}>;
+/** {@link CloudflareDnsProviderConfig} schema. Exact match to the generated schema (includes optional `zone_token`). */
+declare const CloudflareDnsProviderConfigSchema: zod.ZodObject<{
+    api_token: zod.ZodOptional<zod.ZodString>;
+    zone_token: zod.ZodOptional<zod.ZodString>;
+}, "strip", zod.ZodTypeAny, {
+    api_token?: string | undefined;
+    zone_token?: string | undefined;
+}, {
+    api_token?: string | undefined;
+    zone_token?: string | undefined;
+}>;
+/** {@link GodaddyDnsProviderConfig} schema. Exact match to the generated schema. */
+declare const GodaddyDnsProviderConfigSchema: zod.ZodObject<{
+    api_token: zod.ZodOptional<zod.ZodString>;
+}, "strip", zod.ZodTypeAny, {
+    api_token?: string | undefined;
+}, {
+    api_token?: string | undefined;
+}>;
+/**
+ * {@link DigitaloceanDnsProviderConfig} schema.
+ *
+ * Omits the generated schema's `Client` field — a tygo artifact from an
+ * all-unexported Go embed that contributes nothing to real JSON output. See
+ * the equivalent note on {@link DigitaloceanDnsProviderConfig} in `types.ts`.
+ */
+declare const DigitaloceanDnsProviderConfigSchema: zod.ZodObject<Omit<{
+    Client: zod.ZodObject<{}, "strip", zod.ZodTypeAny, {}, {}>;
+    auth_token: zod.ZodString;
+}, "Client">, "strip", zod.ZodTypeAny, {
+    auth_token: string;
+}, {
+    auth_token: string;
+}>;
+
+/**
+ * Build the `caddy-dns/porkbun` provider config.
+ *
+ * @example
+ * buildPorkbunDnsConfig()
+ * // => { providerConfig: { api_key: "{env.PORKBUN_API_KEY}", api_secret_key: "{env.PORKBUN_API_SECRET_KEY}" }, envVars: ["PORKBUN_API_KEY", "PORKBUN_API_SECRET_KEY"] }
+ */
+declare function buildPorkbunDnsConfig(): AcmeDnsProviderConfigResult;
+/**
+ * Build the `caddy-dns/cloudflare` provider config.
+ *
+ * @example
+ * buildCloudflareDnsConfig()
+ * // => { providerConfig: { api_token: "{env.CLOUDFLARE_API_TOKEN}" }, envVars: ["CLOUDFLARE_API_TOKEN"] }
+ */
+declare function buildCloudflareDnsConfig(): AcmeDnsProviderConfigResult;
+/**
+ * Build the `caddy-dns/route53` config.
+ *
+ * Called with no `options` (the default), `caddy-dns/route53` reads
+ * credentials via the AWS Go SDK v2's own default credential chain (env
+ * vars, shared profile, or IAM role) — `providerConfig` is omitted rather
+ * than reimplementing that resolution, exactly as before 0.9.0.
+ *
+ * The plugin also supports an explicit typed `providerConfig` (real,
+ * verified Go source — see {@link Route53DnsProviderConfig}) for callers
+ * who want it instead of relying on ambient credentials: pass any subset of
+ * fields via `options` and they're returned as `providerConfig`.
+ *
+ * @example
+ * buildRoute53DnsConfig()
+ * // => { envVars: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"] }
+ *
+ * @example
+ * buildRoute53DnsConfig({ hosted_zone_id: "Z1D633PJN98FT9", region: "us-east-1" })
+ * // => { providerConfig: { hosted_zone_id: "Z1D633PJN98FT9", region: "us-east-1" }, envVars: [...] }
+ */
+declare function buildRoute53DnsConfig(options?: Route53DnsProviderConfig): AcmeDnsProviderConfigResult;
+/**
+ * Build the `caddy-dns/digitalocean` provider config.
+ *
+ * @example
+ * buildDigitaloceanDnsConfig()
+ * // => { providerConfig: { auth_token: "{env.DIGITALOCEAN_API_TOKEN}" }, envVars: ["DIGITALOCEAN_API_TOKEN"] }
+ */
+declare function buildDigitaloceanDnsConfig(): AcmeDnsProviderConfigResult;
+/**
+ * Build the `caddy-dns/godaddy` provider config.
+ *
+ * `GODADDY_API_TOKEN` must hold GoDaddy's own combined
+ * `"<API_KEY>:<API_SECRET>"` format — see {@link GodaddyDnsProviderConfig}.
+ *
+ * @example
+ * buildGodaddyDnsConfig()
+ * // => { providerConfig: { api_token: "{env.GODADDY_API_TOKEN}" }, envVars: ["GODADDY_API_TOKEN"] }
+ */
+declare function buildGodaddyDnsConfig(): AcmeDnsProviderConfigResult;
+/**
+ * Resolve a `dnsProvider` name (as passed to
+ * {@link buildAcmeDnsPolicy}`.dnsProvider`) to its typed provider config,
+ * via the same normalisation `buildAcmeDnsPolicy` itself uses.
+ *
+ * Unknown provider names return `{ envVars: [] }` — no typed builder
+ * exists yet, so the caller must supply `providerConfig` themselves (e.g.
+ * via the raw `providerConfig` passthrough on `buildAcmeDnsPolicy`).
+ *
+ * @example
+ * buildAcmeDnsPolicy({
+ *   subjects: ["example.com", "*.example.com"],
+ *   dnsProvider: "cloudflare",
+ *   providerConfig: buildAcmeDnsProviderConfig("cloudflare").providerConfig,
+ * });
+ */
+declare function buildAcmeDnsProviderConfig(provider: string): AcmeDnsProviderConfigResult;
+
+/**
+ * caddy-dns plugin integration
+ *
+ * Typed `providerConfig` builders for the `caddy-dns/*` ACME-DNS challenge
+ * provider modules — porkbun, cloudflare, route53, digitalocean, godaddy —
+ * layered on top of `buildAcmeDnsPolicy` (`../caddy/acme.js`), which only
+ * builds the wrapper shape and treats `providerConfig` as an opaque
+ * passthrough.
+ *
+ * @see https://github.com/caddy-dns
+ * @see ../caddy/acme.ts
+ *
+ * @example
+ * ```typescript
+ * import { buildAcmeDnsPolicy } from "@viaalink/caddy-api-client/caddy";
+ * import { buildAcmeDnsProviderConfig } from "@viaalink/caddy-api-client/plugins/caddy-dns";
+ *
+ * const { providerConfig } = buildAcmeDnsProviderConfig("cloudflare");
+ * const policy = buildAcmeDnsPolicy({
+ *   subjects: ["example.com", "*.example.com"],
+ *   dnsProvider: "cloudflare",
+ *   providerConfig,
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+type index_AcmeDnsProviderConfigResult = AcmeDnsProviderConfigResult;
+declare const index_CloudflareDnsProviderConfigSchema: typeof CloudflareDnsProviderConfigSchema;
+type index_DigitaloceanDnsProviderConfig = DigitaloceanDnsProviderConfig;
+declare const index_DigitaloceanDnsProviderConfigSchema: typeof DigitaloceanDnsProviderConfigSchema;
+declare const index_GodaddyDnsProviderConfigSchema: typeof GodaddyDnsProviderConfigSchema;
+declare const index_KNOWN_ACME_DNS_PROVIDERS: typeof KNOWN_ACME_DNS_PROVIDERS;
+type index_KnownAcmeDnsProvider = KnownAcmeDnsProvider;
+declare const index_PorkbunDnsProviderConfigSchema: typeof PorkbunDnsProviderConfigSchema;
+declare const index_buildAcmeDnsProviderConfig: typeof buildAcmeDnsProviderConfig;
+declare const index_buildCloudflareDnsConfig: typeof buildCloudflareDnsConfig;
+declare const index_buildDigitaloceanDnsConfig: typeof buildDigitaloceanDnsConfig;
+declare const index_buildGodaddyDnsConfig: typeof buildGodaddyDnsConfig;
+declare const index_buildPorkbunDnsConfig: typeof buildPorkbunDnsConfig;
+declare const index_buildRoute53DnsConfig: typeof buildRoute53DnsConfig;
+declare namespace index {
+  export { type index_AcmeDnsProviderConfigResult as AcmeDnsProviderConfigResult, type Provider$1 as CloudflareDnsProviderConfig, index_CloudflareDnsProviderConfigSchema as CloudflareDnsProviderConfigSchema, type index_DigitaloceanDnsProviderConfig as DigitaloceanDnsProviderConfig, index_DigitaloceanDnsProviderConfigSchema as DigitaloceanDnsProviderConfigSchema, type Provider as GodaddyDnsProviderConfig, index_GodaddyDnsProviderConfigSchema as GodaddyDnsProviderConfigSchema, index_KNOWN_ACME_DNS_PROVIDERS as KNOWN_ACME_DNS_PROVIDERS, type index_KnownAcmeDnsProvider as KnownAcmeDnsProvider, type Provider$2 as PorkbunDnsProviderConfig, index_PorkbunDnsProviderConfigSchema as PorkbunDnsProviderConfigSchema, index_buildAcmeDnsProviderConfig as buildAcmeDnsProviderConfig, index_buildCloudflareDnsConfig as buildCloudflareDnsConfig, index_buildDigitaloceanDnsConfig as buildDigitaloceanDnsConfig, index_buildGodaddyDnsConfig as buildGodaddyDnsConfig, index_buildPorkbunDnsConfig as buildPorkbunDnsConfig, index_buildRoute53DnsConfig as buildRoute53DnsConfig };
+}
+
+export { type AcmeDnsProviderConfigResult as A, CloudflareDnsProviderConfigSchema as C, type DigitaloceanDnsProviderConfig as D, GodaddyDnsProviderConfigSchema as G, type KnownAcmeDnsProvider as K, type Provider$2 as P, type Provider$1 as a, type Provider as b, KNOWN_ACME_DNS_PROVIDERS as c, PorkbunDnsProviderConfigSchema as d, DigitaloceanDnsProviderConfigSchema as e, buildPorkbunDnsConfig as f, buildCloudflareDnsConfig as g, buildRoute53DnsConfig as h, index as i, buildDigitaloceanDnsConfig as j, buildGodaddyDnsConfig as k, buildAcmeDnsProviderConfig as l };