@giveitsmaller/sdk 0.4.0 → 0.7.0

package/dist/credentials.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Credential + endpoint resolution for the ergonomic-layer `gisl.create()`
+ * factory. Implements an AWS-style short-circuiting chain:
+ *   API key:    explicit arg → `GISL_API_KEY` env → `~/.gisl/credentials` profile
+ *   Endpoint:   explicit arg → `GISL_ENVIRONMENT` / `GISL_BASE_URL` env → prod default
+ *
+ * Sources are tried in order; the first hit wins. Malformed profile files
+ * surface as `GislConfigError` naming the offending profile (NEVER the value
+ * — credential values must not appear in error messages).
+ *
+ * Browser-safe: profile-file lookups dynamic-import `node:fs/promises` only
+ * when a profile path is requested AND a Node runtime is detected; missing
+ * fs in the browser yields the typed
+ * `GislConfigError('profile_unavailable_in_runtime')`.
+ */
+export declare const GISL_API_KEY_ENV = "GISL_API_KEY";
+export declare const GISL_BASE_URL_ENV = "GISL_BASE_URL";
+export declare const GISL_ENVIRONMENT_ENV = "GISL_ENVIRONMENT";
+/**
+ * Named environments → base URLs. Kept colocated with the resolver so the
+ * mapping table doesn't leak into `gisl.ts`.
+ */
+export declare const ENVIRONMENT_ENDPOINTS: {
+    readonly prod: "https://api.giveitsmaller.com";
+    readonly staging: "https://api.staging.giveitsmaller.com";
+};
+export type Environment = keyof typeof ENVIRONMENT_ENDPOINTS;
+export declare const DEFAULT_ENDPOINT: "https://api.giveitsmaller.com";
+export interface ResolveCredentialsOptions {
+    /** Explicit API key — highest precedence. */
+    readonly apiKey?: string;
+    /** Profile name from `~/.gisl/credentials`. Default: `'default'`. */
+    readonly profile?: string;
+    /**
+     * Cookie-mode flag. When `true`, the caller is authenticating via
+     * session cookie (browser SPA flow) and a missing apiKey is NOT a
+     * configuration error — `resolveApiKey` returns `null` without
+     * throwing, and the ergonomic-layer factory accepts it.
+     */
+    readonly useSessionCookie?: boolean;
+    /** Override the profile-file path (testing). */
+    readonly profilePath?: string;
+}
+export interface ResolveEndpointOptions {
+    readonly baseUrl?: string;
+    readonly environment?: Environment;
+}
+/**
+ * Resolve the API key via the credential chain. Returns the resolved key,
+ * or `null` if no source produced one. The ergonomic-layer factory is
+ * responsible for deciding whether `null` is an error (default: yes, throw
+ * `GislMissingCredentialsError`) or acceptable (anonymous / cookie-mode).
+ */
+export declare function resolveApiKey(opts?: ResolveCredentialsOptions): Promise<string | null>;
+/**
+ * Resolve the base URL. Explicit `baseUrl` wins; otherwise an explicit
+ * `environment` name; otherwise the `GISL_BASE_URL` / `GISL_ENVIRONMENT`
+ * env vars; otherwise the prod default. Never throws — the chain always
+ * resolves to a usable URL.
+ */
+export declare function resolveEndpoint(opts?: ResolveEndpointOptions): string;

package/dist/credentials.js

@@ -0,0 +1,200 @@
+/**
+ * Credential + endpoint resolution for the ergonomic-layer `gisl.create()`
+ * factory. Implements an AWS-style short-circuiting chain:
+ *   API key:    explicit arg → `GISL_API_KEY` env → `~/.gisl/credentials` profile
+ *   Endpoint:   explicit arg → `GISL_ENVIRONMENT` / `GISL_BASE_URL` env → prod default
+ *
+ * Sources are tried in order; the first hit wins. Malformed profile files
+ * surface as `GislConfigError` naming the offending profile (NEVER the value
+ * — credential values must not appear in error messages).
+ *
+ * Browser-safe: profile-file lookups dynamic-import `node:fs/promises` only
+ * when a profile path is requested AND a Node runtime is detected; missing
+ * fs in the browser yields the typed
+ * `GislConfigError('profile_unavailable_in_runtime')`.
+ */
+import { GislConfigError } from './errors.js';
+// ---------------------------------------------------------------------------
+// Environment constants
+// ---------------------------------------------------------------------------
+export const GISL_API_KEY_ENV = 'GISL_API_KEY';
+export const GISL_BASE_URL_ENV = 'GISL_BASE_URL';
+export const GISL_ENVIRONMENT_ENV = 'GISL_ENVIRONMENT';
+/**
+ * Named environments → base URLs. Kept colocated with the resolver so the
+ * mapping table doesn't leak into `gisl.ts`.
+ */
+export const ENVIRONMENT_ENDPOINTS = {
+    prod: 'https://api.giveitsmaller.com',
+    staging: 'https://api.staging.giveitsmaller.com',
+};
+export const DEFAULT_ENDPOINT = ENVIRONMENT_ENDPOINTS.prod;
+// ---------------------------------------------------------------------------
+// Public resolvers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the API key via the credential chain. Returns the resolved key,
+ * or `null` if no source produced one. The ergonomic-layer factory is
+ * responsible for deciding whether `null` is an error (default: yes, throw
+ * `GislMissingCredentialsError`) or acceptable (anonymous / cookie-mode).
+ */
+export async function resolveApiKey(opts = {}) {
+    // 1. Explicit wins.
+    if (typeof opts.apiKey === 'string' && opts.apiKey.length > 0) {
+        return opts.apiKey;
+    }
+    // 2. Environment variable.
+    const envKey = readEnv(GISL_API_KEY_ENV);
+    if (envKey !== null && envKey.length > 0) {
+        return envKey;
+    }
+    // 3. Shared-config profile (`~/.gisl/credentials`). Skipped silently
+    //    when running in a non-Node runtime (browser, edge) — the resolver
+    //    returns `null` and the caller decides whether that's fatal.
+    if (!isNodeRuntime()) {
+        return null;
+    }
+    const profileName = opts.profile ?? 'default';
+    const profilePath = opts.profilePath ?? defaultProfilePath();
+    if (profilePath === null) {
+        return null;
+    }
+    const profileEntries = await readProfile(profilePath, profileName);
+    if (profileEntries === null) {
+        return null;
+    }
+    const profileKey = profileEntries.api_key;
+    if (typeof profileKey === 'string' && profileKey.length > 0) {
+        return profileKey;
+    }
+    return null;
+}
+/**
+ * Resolve the base URL. Explicit `baseUrl` wins; otherwise an explicit
+ * `environment` name; otherwise the `GISL_BASE_URL` / `GISL_ENVIRONMENT`
+ * env vars; otherwise the prod default. Never throws — the chain always
+ * resolves to a usable URL.
+ */
+export function resolveEndpoint(opts = {}) {
+    if (typeof opts.baseUrl === 'string' && opts.baseUrl.length > 0) {
+        return opts.baseUrl;
+    }
+    if (typeof opts.environment === 'string') {
+        const explicitEnv = ENVIRONMENT_ENDPOINTS[opts.environment];
+        if (explicitEnv !== undefined) {
+            return explicitEnv;
+        }
+        // Codex r2 medium 23a17c1dbf75 — fail-closed on an unknown explicit
+        // environment name. A typo or JS-side caller previously silently fell
+        // through to env-var / prod default, which can mis-route a staging-
+        // intended request to production. The env-var path still allows
+        // unknown values to fall through (low-impact since it's an env config,
+        // not a code-level arg).
+        throw new GislConfigError(`Unknown environment '${opts.environment}'. Valid values: ${Object.keys(ENVIRONMENT_ENDPOINTS).join(', ')}.`);
+    }
+    const envBaseUrl = readEnv(GISL_BASE_URL_ENV);
+    if (envBaseUrl !== null && envBaseUrl.length > 0) {
+        return envBaseUrl;
+    }
+    const envEnvironment = readEnv(GISL_ENVIRONMENT_ENV);
+    if (envEnvironment !== null) {
+        const envMapped = ENVIRONMENT_ENDPOINTS[envEnvironment];
+        if (envMapped !== undefined) {
+            return envMapped;
+        }
+    }
+    return DEFAULT_ENDPOINT;
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function isNodeRuntime() {
+    return (typeof process !== 'undefined' &&
+        process.versions !== undefined &&
+        typeof process.versions.node === 'string');
+}
+function readEnv(name) {
+    if (!isNodeRuntime()) {
+        return null;
+    }
+    const value = process.env[name];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function defaultProfilePath() {
+    const homeDir = readEnv('HOME') ?? readEnv('USERPROFILE');
+    if (homeDir === null) {
+        return null;
+    }
+    // Use forward-slash join — Node accepts it on every platform.
+    return `${homeDir}/.gisl/credentials`;
+}
+/**
+ * Read a single profile section from an INI-format credentials file.
+ * Returns `null` when the file does not exist; throws `GislConfigError`
+ * when the file exists but is malformed or the requested profile is
+ * absent. Never includes credential VALUES in error messages.
+ */
+async function readProfile(path, profileName) {
+    let raw;
+    try {
+        // Lazy import keeps `node:fs` out of browser bundles.
+        const fs = await import('node:fs/promises');
+        raw = await fs.readFile(path, 'utf8');
+    }
+    catch (err) {
+        // ENOENT → no file = no credentials from this source (not an error).
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return null;
+        }
+        throw new GislConfigError(`Failed to read shared credentials file at ${path}: ${code ?? 'unknown error'}`);
+    }
+    const parsed = parseIni(raw, path);
+    const entries = parsed[profileName];
+    if (entries === undefined) {
+        throw new GislConfigError(`Profile '${profileName}' not found in shared credentials file at ${path}`);
+    }
+    return entries;
+}
+/**
+ * Minimal INI parser sufficient for AWS-style credentials files: section
+ * headers `[name]`, `key = value` lines, `#` and `;` comments. Whitespace
+ * around `=` is trimmed. No nested sections, no interpolation, no quoting.
+ * Throws `GislConfigError` on malformed lines, naming only the LINE NUMBER
+ * and PROFILE — never the value.
+ */
+function parseIni(raw, sourcePath) {
+    const sections = {};
+    let currentSection = null;
+    const lines = raw.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line === '' || line.startsWith('#') || line.startsWith(';')) {
+            continue;
+        }
+        if (line.startsWith('[') && line.endsWith(']')) {
+            currentSection = line.slice(1, -1).trim();
+            if (currentSection === '') {
+                throw new GislConfigError(`Empty section header at line ${i + 1} in ${sourcePath}`);
+            }
+            if (sections[currentSection] === undefined) {
+                sections[currentSection] = {};
+            }
+            continue;
+        }
+        if (currentSection === null) {
+            throw new GislConfigError(`Key-value line at line ${i + 1} in ${sourcePath} is outside any section header`);
+        }
+        const eqIndex = line.indexOf('=');
+        if (eqIndex === -1) {
+            throw new GislConfigError(`Malformed line ${i + 1} in ${sourcePath} (expected key=value)`);
+        }
+        const key = line.slice(0, eqIndex).trim();
+        if (key === '') {
+            throw new GislConfigError(`Empty key at line ${i + 1} in ${sourcePath}`);
+        }
+        const value = line.slice(eqIndex + 1).trim();
+        sections[currentSection][key] = value;
+    }
+    return sections;
+}

package/dist/ergonomic/preset_resolver.d.ts

@@ -0,0 +1,75 @@
+import type { ResolvedOptions } from '../builder.js';
+import type { OptimizeFor } from '../generated/sdk_spec/enums.js';
+import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/index.js';
+/** Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value. */
+export declare const PRESET_VERSION = "1.0";
+/**
+ * Inputs to {@link resolveCompressOptions}. `media` selects which leaf
+ * DTO drives sdkDefault + clientDefault lookups + invalid-combo
+ * validations. `op` is currently always `'compress'`; future ops will
+ * extend the union.
+ */
+export interface ResolveCompressOptionsInput {
+    readonly media: PresetMedia;
+    readonly op: PresetOp;
+    /** Defaults registered via `gisl.create({ presetDefaults: ... })`. */
+    readonly presetDefaults?: PresetDefaults;
+    /**
+     * Scoped defaults attached via `client.withPresetDefaults(...)` (T4c —
+     * `ULAlOP6j`). Layered between `presetDefaults` and `presetOverrides`
+     * in the resolver chain. The derived client closes over this
+     * reference; `undefined` for clients that never went through a
+     * `withPresetDefaults` call.
+     */
+    readonly scopedPresetDefaults?: PresetDefaults;
+    /** Per-call `presetOverrides` argument from the operation builder. */
+    readonly presetOverrides?: Readonly<Record<string, unknown>>;
+    /**
+     * `optimize` selects the preset level. When unset, NO shipped
+     * defaults apply (resolver layer 1 contributes nothing); the
+     * resulting `resolvedOptions.preset` is `null`.
+     */
+    readonly optimize?: OptimizeFor;
+    /**
+     * Explicit per-call knobs the caller passed alongside `optimize` —
+     * e.g. `{ autoOrient: true }`. These are the highest-precedence
+     * layer.
+     */
+    readonly explicitOptions: Readonly<Record<string, unknown>>;
+}
+/**
+ * Output of {@link resolveCompressOptions}. `wireOptions` is the
+ * snake_case payload ready for the operation argument; `resolvedOptions`
+ * is the introspection projection surfaced on `Result.resolvedOptions`.
+ */
+export interface ResolveCompressOptionsOutput {
+    readonly wireOptions: Record<string, unknown>;
+    readonly resolvedOptions: ResolvedOptions;
+}
+/**
+ * Parse a `targetSize` value into a positive integer byte count.
+ *
+ * - Integer input passes through after non-negative + finite checks.
+ * - String input must match `<number><unit?>` with unit in
+ *   `B|KB|MB|GB|TB` (case-insensitive). Multipliers are BINARY
+ *   (1 KB = 1024). Decimal fractions allowed in the magnitude
+ *   (`'1.5GB'` → `1.5 * 2^30` rounded down to integer bytes).
+ *
+ * Throws {@link GislConfigError} with `reason: 'invalid_target_size'`
+ * on any other input — including negative numbers, infinities, missing
+ * magnitude, unknown unit, or zero magnitude.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function _parseTargetSize(value: unknown): number;
+/**
+ * Resolve the wire payload + introspection projection for a compress
+ * operation call. Throws {@link GislConfigError} before any network
+ * round-trip when the merged options violate a documented constraint.
+ *
+ * Layers are applied in fixed order:
+ *   SDK shipped → client default → scoped (T4c) → callPresetOverride → explicit.
+ *
+ * `optimize` unset ⇒ layer 1 contributes nothing; `resolvedOptions.preset = null`.
+ */
+export declare function resolveCompressOptions(input: ResolveCompressOptionsInput): ResolveCompressOptionsOutput;