@funyard-org/cli 0.0.0-stage → 0.6.3

package/src/client.js

@@ -0,0 +1,506 @@
+import { KNOWN_CAPABILITY_IDS } from './capabilities.js';
+import {
+  REQUEST_ID,
+  CALL_ID,
+  FIELD_ID,
+  matches,
+  callIdentitySchema,
+  submissionSchema,
+  resultMatches,
+  fieldsResultMatches,
+  exploreRequestSchema,
+  fieldsQuoteRequestSchema,
+  fieldsQuoteSchema,
+} from './protocol/index.js';
+
+/** Comma list or array of canonical field ids, normalized the way the server fingerprints it. */
+export function fieldList(value) {
+  const ids = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [];
+  const normalized = [...new Set(ids.map(id => (typeof id === 'string' ? id.trim() : '')).filter(Boolean))].sort();
+  if (!normalized.length || normalized.length > 64 || !normalized.every(id => FIELD_ID.test(id)))
+    throw new FunyardError('Provide 1-64 canonical field ids such as finance.quote.price.', {
+      code: 'INVALID_ARGUMENTS',
+    });
+  return normalized.join(',');
+}
+export { REQUEST_ID, CALL_ID } from './protocol/index.js';
+
+export const DEFAULT_BASE_URL = 'https://funyard.org';
+const CAPABILITY_NAME = /^[a-z][a-z0-9_]{0,31}\.[a-z][a-z0-9_]{0,31}$/;
+const SAFE_API_CODES = new Set([
+  'INVALID_KEY',
+  'UNAUTHORIZED',
+  'FORBIDDEN',
+  'ACCOUNT_UNAVAILABLE',
+  'CAPABILITY_DENIED',
+  'CAPABILITY_NOT_FOUND',
+  'CAPABILITY_UNAVAILABLE',
+  'INVALID_ARGUMENTS',
+  'INVALID_REQUEST_ID',
+  'IDEMPOTENCY_CONFLICT',
+  'INSUFFICIENT_BALANCE',
+  'QUEUE_LIMIT',
+  'HOLD_LIMIT',
+  'RATE_LIMITED',
+  'PROVIDER_CAPACITY',
+  'NOT_CANCELLABLE',
+  'CALL_NOT_FOUND',
+  'NOT_FOUND',
+  'KEY_IN_URL_FORBIDDEN',
+  'REQUEST_TOO_LARGE',
+  'INVALID_INTEGER',
+  'INVALID_WINDOW',
+  'INVALID_JSON',
+  'INGRESS_RATE_LIMITED',
+  'INTERNAL_ERROR',
+  'ACCOUNTING_UNAVAILABLE',
+  'INVALID_API_KEY',
+  'ACCOUNT_DISABLED',
+  'CAPABILITY_FORBIDDEN',
+  'INVALID_REQUEST',
+  'INVALID_CONTENT_TYPE',
+  'REQUEST_ID_CONFLICT',
+  'CALL_ALREADY_DISPATCHED',
+  'PROVIDER_NOT_CONFIGURED',
+  'PROVIDER_DISABLED',
+  'PROVIDER_COOLDOWN',
+  'SERVICE_UNAVAILABLE',
+  'CANCELLED',
+  'QUEUE_EXPIRED',
+  'RESULT_UNKNOWN',
+  'INGRESS_RPM',
+  'RESULT_READ_RPM',
+  'SUBMISSION_RPM',
+  'CANCEL_RPM',
+  'ACCOUNT_RPM',
+  'KEY_RPM',
+  'ACCOUNT_DAILY_CALLS',
+  'KEY_DAILY_CALLS',
+  'ACCOUNT_DAILY_POINTS',
+  'KEY_DAILY_POINTS',
+  'ACCOUNT_QUEUE_LIMIT',
+  'KEY_QUEUE_LIMIT',
+  'ACCOUNT_HELD_LIMIT',
+  'KEY_HELD_LIMIT',
+  'OUTCOME_PENDING',
+  'INVALID_QUERY',
+  'PROVIDER_QUOTA',
+  'PROVIDER_CYCLE_NOT_STARTED',
+]);
+
+export class FunyardError extends Error {
+  constructor(message, { status, code, requestId, callId, reason, retryAfter } = {}) {
+    super(message);
+    this.name = 'FunyardError';
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.callId = callId;
+    this.reason = reason;
+    this.retryAfter = retryAfter;
+  }
+}
+
+export function validateBaseURL(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new FunyardError('Invalid API base URL.');
+  }
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (
+    (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    (url.pathname !== '/' && url.pathname !== '')
+  ) {
+    throw new FunyardError(
+      'API base URL must be an HTTPS origin (HTTP is allowed only on localhost), without credentials, path, query or fragment.',
+    );
+  }
+  return url.origin;
+}
+
+function identifier(value, name) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 256 || /[\x00-\x1f\x7f]/.test(value))
+    throw new FunyardError(`Invalid ${name}.`);
+  return value;
+}
+
+function requestIdentifier(value) {
+  if (typeof value !== 'string' || !REQUEST_ID.test(value))
+    throw new FunyardError(
+      'Supply an explicit request ID: 1–64 lowercase letters, digits, underscores or hyphens, beginning with a letter or digit.',
+      { code: 'INVALID_REQUEST_ID' },
+    );
+  return value;
+}
+
+function callIdentifier(value) {
+  if (typeof value !== 'string' || !CALL_ID.test(value))
+    throw new FunyardError('A valid call_ ID is required.', { code: 'INVALID_CALL_ID' });
+  return value;
+}
+
+function trustedCall(response, expected) {
+  if (
+    !matches(callIdentitySchema, response) ||
+    Object.entries(expected).some(([field, value]) => response[field] !== value)
+  ) {
+    throw new FunyardError(
+      'The response does not match the original call. Query the same ID before doing anything else.',
+      {
+        code: 'RESPONSE_UNKNOWN',
+        reason: 'CALL_IDENTITY_INVALID',
+        requestId: expected.request_id,
+        callId: expected.call_id,
+      },
+    );
+  }
+  // Capabilities this build knows are checked strictly; a field capability the server added later
+  // is accepted only in the shared field-result shape. Anything else fails closed.
+  const known = KNOWN_CAPABILITY_IDS.includes(response.capability);
+  if (
+    Object.hasOwn(response, 'data') &&
+    !(known
+      ? resultMatches(response.capability, response.status, response.data)
+      : fieldsResultMatches(response.status, response.data))
+  ) {
+    throw new FunyardError(
+      'The result does not match the V1 capability contract. Query the same ID before doing anything else.',
+      {
+        code: 'RESPONSE_UNKNOWN',
+        reason: 'CALL_RESULT_INVALID',
+        requestId: expected.request_id ?? response.request_id,
+        callId: expected.call_id ?? response.call_id,
+      },
+    );
+  }
+  return response;
+}
+
+function httpError(response, data, requestId) {
+  const candidate = data?.error?.code ?? data?.code;
+  const code = SAFE_API_CODES.has(candidate) ? candidate : 'HTTP_ERROR';
+  const header = response.headers.get('retry-after');
+  let retryAfter;
+  if (header && /^\d+$/.test(header)) {
+    const seconds = Number(header);
+    if (Number.isSafeInteger(seconds) && seconds <= 86400) retryAfter = seconds;
+  } else if (
+    header &&
+    /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(
+      header,
+    )
+  ) {
+    const seconds = Math.max(0, Math.ceil((Date.parse(header) - Date.now()) / 1000));
+    if (Number.isSafeInteger(seconds) && seconds <= 86400) retryAfter = seconds;
+  }
+  return new FunyardError(`API request failed (HTTP ${response.status}).`, {
+    status: response.status,
+    code,
+    requestId,
+    retryAfter,
+  });
+}
+
+function validFieldQuotePath(path) {
+  if (typeof path !== 'string' || !path.startsWith('/fields/quote?') || path.includes('#') || path.length > 16384)
+    return false;
+  const query = new URLSearchParams(path.slice('/fields/quote?'.length));
+  if (
+    [...new Set(query.keys())].some(key => query.getAll(key).length !== 1) ||
+    [...query.keys()].some(key => !['fields', 'sources', 'capability', 'arguments'].includes(key))
+  )
+    return false;
+  try {
+    fieldList(query.get('fields'));
+    if (!query.has('sources')) return [...query.keys()].length === 1;
+    const input = {
+      fields: query.get('fields'),
+      sources: query.get('sources'),
+      capability: query.get('capability'),
+      arguments: JSON.parse(query.get('arguments') ?? '{}'),
+    };
+    return matches(fieldsQuoteRequestSchema, input) && input.sources === 'all';
+  } catch {
+    return false;
+  }
+}
+
+export class FunyardClient {
+  constructor(options = process.env, extra = {}) {
+    const apiKey = options.apiKey ?? options.FUNYARD_API_KEY ?? process.env.FUNYARD_API_KEY;
+    const baseURL = options.baseURL ?? options.FUNYARD_BASE_URL ?? process.env.FUNYARD_BASE_URL ?? DEFAULT_BASE_URL;
+    const timeoutMs = extra.timeoutMs ?? options.timeoutMs ?? 30_000;
+    const fetchImpl = extra.fetch ?? options.fetch ?? globalThis.fetch;
+    this.baseURL = validateBaseURL(baseURL);
+    if (typeof apiKey !== 'string' || !apiKey.trim() || /[\s\x00-\x1f\x7f]/.test(apiKey))
+      throw new FunyardError('A valid API key is required. Use FUNYARD_API_KEY or funyard login.');
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 300_000)
+      throw new FunyardError('Invalid request timeout.');
+    Object.defineProperty(this, 'apiKey', { value: apiKey });
+    this.timeoutMs = timeoutMs;
+    this.fetch = fetchImpl;
+    const diagnostic = extra.onDiagnostic ?? options.onDiagnostic;
+    if (diagnostic !== undefined && typeof diagnostic !== 'function')
+      throw new FunyardError('Invalid diagnostic callback.');
+    this.onDiagnostic = diagnostic ?? (event => process.stderr.write(`${JSON.stringify(event)}\n`));
+  }
+
+  async request(path, options = {}, legacyOptions = {}) {
+    // Preserve the published SDK's request(method, route, options) entry point.
+    if (['GET', 'POST'].includes(path) && typeof options === 'string') {
+      const method = path;
+      path = options;
+      options = { ...legacyOptions, method, requestId: legacyOptions.requestID, callId: legacyOptions.callID };
+    }
+    const { method = 'GET', body, requestId, callId, signal } = options;
+    if (
+      !['GET', 'POST'].includes(method) ||
+      typeof path !== 'string' ||
+      (!validFieldQuotePath(path) &&
+        !/^\/(?:me|usage(?:\?[^#]*)?|capabilities(?:\/[a-z.]+)?|fields(?:\?category=[a-z]{1,32})?|fields\/quote\?fields=[A-Za-z0-9_.,%]+|explore(?:\?(?:domain|capability|group|q)=[A-Za-z0-9_.%-]{1,900})?|calls(?:\?request_id=[a-z0-9_-]+|\/call_[A-Za-z0-9_-]+(?:\/cancel)?)?)$/.test(
+          path,
+        ))
+    )
+      throw new FunyardError('Unsupported API route.', { code: 'INVALID_ARGUMENTS' });
+    if (body !== undefined && Buffer.byteLength(JSON.stringify(body)) > 65536)
+      throw new FunyardError('Request body exceeds 64 KiB.', { code: 'REQUEST_TOO_LARGE', requestId, callId });
+    const uncertain = reason =>
+      new FunyardError(
+        'No trustworthy response was received. Query the original ID; never submit a replacement automatically.',
+        { code: 'RESPONSE_UNKNOWN', reason, requestId, callId },
+      );
+    const retry = async (reason, status) => {
+      const event = { event: 'funyard_retry', method: 'GET', attempt: 2, reason, ...(status ? { status } : {}) };
+      try {
+        this.onDiagnostic(event);
+      } catch {
+        /* Diagnostics never change request semantics. */
+      }
+      await new Promise(resolve => setTimeout(resolve, 150));
+    };
+    const connectionInterrupted = error =>
+      error?.name === 'TypeError' ||
+      ['ECONNRESET', 'EPIPE', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'EAI_AGAIN'].includes(
+        error?.cause?.code ?? error?.code,
+      );
+    for (let attempt = 0; attempt < 2; attempt++) {
+      let response;
+      try {
+        response = await this.fetch(`${this.baseURL}/funyard/v1${path}`, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            ...(body ? { 'Content-Type': 'application/json' } : {}),
+          },
+          ...(body ? { body: JSON.stringify(body) } : {}),
+          signal: signal
+            ? AbortSignal.any([signal, AbortSignal.timeout(this.timeoutMs)])
+            : AbortSignal.timeout(this.timeoutMs),
+          // Manual mode refuses redirects without turning a redirect into a retryable transport error.
+          redirect: 'manual',
+        });
+      } catch (error) {
+        if (method === 'GET' && attempt === 0 && !signal?.aborted && connectionInterrupted(error)) {
+          await retry('connection_interrupted');
+          continue;
+        }
+        throw uncertain(signal?.aborted ? 'ABORT_ERR' : 'NETWORK_ERROR');
+      }
+      let data;
+      if (response.status >= 300 && response.status < 400) throw uncertain('REDIRECT_REJECTED');
+      if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type') ?? ''))
+        throw uncertain('CONTENT_TYPE_INVALID');
+      try {
+        const reader = response.body?.getReader();
+        let size = 0;
+        const chunks = [];
+        if (reader)
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            size += value.byteLength;
+            if (size > 1_048_576) {
+              await reader.cancel();
+              throw uncertain('RESPONSE_TOO_LARGE');
+            }
+            chunks.push(Buffer.from(value));
+          }
+        data = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      } catch (error) {
+        if (error instanceof FunyardError) throw error;
+        if (method === 'GET' && attempt === 0 && response.ok && connectionInterrupted(error)) {
+          await retry('connection_interrupted');
+          continue;
+        }
+        if (!response.ok) throw httpError(response, undefined, requestId);
+        throw uncertain('JSON_INVALID');
+      }
+      if (!data || typeof data !== 'object' || Array.isArray(data)) throw uncertain('RESPONSE_SHAPE_INVALID');
+      if (!response.ok) {
+        // Only parsed JSON responses in this explicit GET allowlist may retry.
+        if (method === 'GET' && attempt === 0 && [408, 502, 503, 504].includes(response.status)) {
+          await retry('http_transient', response.status);
+          continue;
+        }
+        throw httpError(response, data, requestId);
+      }
+      return JSON.parse(redact(data, this.apiKey));
+    }
+  }
+
+  me(signal) {
+    return this.request('/me', { signal });
+  }
+  async capabilities(id, { signal } = {}) {
+    const response = await this.request(
+      id === undefined ? '/capabilities' : `/capabilities/${encodeURIComponent(identifier(id, 'capability'))}`,
+      { signal },
+    );
+    return response;
+  }
+  usage(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).length)
+      throw new FunyardError('V1 usage returns the latest 100 account ledger entries and does not accept filters.', {
+        code: 'INVALID_ARGUMENTS',
+      });
+    return this.request('/usage');
+  }
+  /** Field catalog: ids, their billing group and the group's price. Optional category filter. */
+  fields(category, { signal } = {}) {
+    if (category !== undefined && !/^[a-z]{1,32}$/.test(category))
+      throw new FunyardError('Invalid field category.', { code: 'INVALID_ARGUMENTS' });
+    return this.request(category === undefined ? '/fields' : `/fields?category=${category}`, { signal });
+  }
+  /** Progressive discovery: no option lists domains; one of domain, capability, group or q opens that level. */
+  explore(options = {}, { signal } = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+      throw new FunyardError('Explore options must be an object.', { code: 'INVALID_ARGUMENTS' });
+    const entries = Object.entries(options).filter(([, value]) => value !== undefined);
+    if (entries.length > 1 || !matches(exploreRequestSchema, Object.fromEntries(entries)))
+      throw new FunyardError('Use at most one of domain, capability, group or q.', { code: 'INVALID_ARGUMENTS' });
+    const [entry] = entries;
+    return this.request(entry ? `/explore?${entry[0]}=${encodeURIComponent(entry[1])}` : '/explore', { signal });
+  }
+  /** Dry-run price for a field list; nothing is reserved or charged. */
+  fieldsQuote(fields, { signal, sources, capability, arguments: args } = {}) {
+    const normalized = fieldList(fields);
+    let path = `/fields/quote?fields=${encodeURIComponent(normalized)}`;
+    if (sources !== undefined || capability !== undefined || args !== undefined) {
+      const input = { fields: normalized, sources, capability, arguments: args ?? {} };
+      if (sources !== 'all' || !matches(fieldsQuoteRequestSchema, input))
+        throw new FunyardError('Multi-source quotes require sources=all, a capability and string arguments.', {
+          code: 'INVALID_ARGUMENTS',
+        });
+      path += `&sources=all&capability=${encodeURIComponent(capability)}&arguments=${encodeURIComponent(JSON.stringify(args ?? {}))}`;
+    }
+    return this.request(path, { signal }).then(result => {
+      if (
+        sources === 'all' &&
+        (!matches(fieldsQuoteSchema, result) || result.sources !== 'all' || result.lines.some(line => !line.source))
+      )
+        throw new FunyardError('Server did not confirm a multi-source quote.', { code: 'INVALID_RESPONSE' });
+      return result;
+    });
+  }
+  async call(capability, args = {}, { requestId, signal } = {}) {
+    // The server decides what exists; this only refuses malformed names.
+    if (typeof capability !== 'string' || !CAPABILITY_NAME.test(capability))
+      throw new FunyardError('Unknown capability.', { code: 'INVALID_ARGUMENTS' });
+    requestIdentifier(requestId);
+    if (!matches(submissionSchema, { request_id: requestId, capability, arguments: args }))
+      throw new FunyardError('Arguments must be an object of strings.');
+    return trustedCall(
+      await this.request('/calls', {
+        method: 'POST',
+        body: { request_id: requestId, capability, arguments: args },
+        requestId,
+        signal,
+      }),
+      { request_id: requestId, capability },
+    );
+  }
+  create(capability, requestId, args = {}, signal) {
+    return this.call(capability, args, { requestId: requestIdentifier(requestId), signal });
+  }
+  getCall(args = {}, signal) {
+    if (
+      !args ||
+      typeof args !== 'object' ||
+      Array.isArray(args) ||
+      Object.keys(args).length !== 1 ||
+      !Object.keys(args).every(key => ['call_id', 'request_id'].includes(key))
+    )
+      throw new FunyardError('Provide exactly one call ID or request ID.');
+    return this.status({ callId: args.call_id, requestId: args.request_id }, signal);
+  }
+  status({ callId, requestId } = {}, signal) {
+    if ((callId !== undefined) === (requestId !== undefined))
+      throw new FunyardError('Provide exactly one call ID or request ID.');
+    const expected =
+      callId !== undefined ? { call_id: callIdentifier(callId) } : { request_id: requestIdentifier(requestId) };
+    return this.request(callId !== undefined ? `/calls/${callId}` : `/calls?request_id=${requestId}`, {
+      requestId,
+      callId,
+      signal,
+    }).then(response => trustedCall(response, expected));
+  }
+  cancel(callId, signal) {
+    callIdentifier(callId);
+    return this.request(`/calls/${callId}/cancel`, { method: 'POST', body: {}, callId, signal }).then(response =>
+      trustedCall(response, { call_id: callId }),
+    );
+  }
+}
+
+export function safeError(error) {
+  if (!(error instanceof FunyardError)) return { error: { message: 'Operation failed.' } };
+  return {
+    error: {
+      message: error.message,
+      ...(error.code ? { code: error.code } : {}),
+      ...(error.status ? { status: error.status } : {}),
+      ...(error.retryAfter !== undefined ? { retry_after: error.retryAfter } : {}),
+      ...(error.requestId
+        ? {
+            request_id: error.requestId,
+            recovery:
+              'Use funyard status --request-id with this request ID and the same API base URL before resubmitting.',
+          }
+        : {}),
+      ...(error.callId
+        ? {
+            call_id: error.callId,
+            recovery: 'Use funyard status --call-id with the original call ID before resubmitting.',
+          }
+        : {}),
+    },
+    ...(error.reason ? { transport_reason: error.reason } : {}),
+    ...(error.requestId
+      ? { request_id: error.requestId, recovery: { command: 'status', request_id: error.requestId } }
+      : error.callId
+        ? { call_id: error.callId, recovery: { command: 'status', call_id: error.callId } }
+        : {}),
+  };
+}
+
+export function redact(value, secret) {
+  // Apply to successful responses too: an upstream must not cause key disclosure.
+  let encoded = JSON.stringify(value);
+  if (encoded === undefined) return 'null';
+  if (secret)
+    for (const variant of new Set([
+      secret,
+      encodeURIComponent(secret),
+      Buffer.from(secret).toString('base64'),
+      Buffer.from(secret).toString('base64url'),
+    ]))
+      encoded = encoded.split(JSON.stringify(variant).slice(1, -1)).join('[REDACTED]');
+  return encoded;
+}

package/src/config.js

@@ -0,0 +1,81 @@
+import { open, mkdir, rename, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { FunyardError, validateBaseURL } from './client.js';
+
+export function configPath(env = process.env) {
+  return env.FUNYARD_CONFIG_FILE || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'funyard', 'config.json');
+}
+
+export async function readConfig(path = configPath()) {
+  let file;
+  try {
+    file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await file.stat();
+    if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || (process.getuid && stat.uid !== process.getuid()))
+      throw new FunyardError('Config must be owned by this user and have permissions 600.');
+    const config = JSON.parse(await file.readFile('utf8'));
+    if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('invalid');
+    if (config.baseURL) validateBaseURL(config.baseURL);
+    return config;
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    if (error instanceof FunyardError) throw error;
+    throw new FunyardError('Unable to read secure config file.');
+  } finally {
+    await file?.close();
+  }
+}
+
+export async function writeConfig(config, path = configPath()) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  let file;
+  try {
+    file = await open(temporary, 'wx', 0o600);
+    await file.writeFile(`${JSON.stringify(config, null, 2)}\n`);
+    await file.sync();
+    await file.close();
+    file = undefined;
+    await rename(temporary, path);
+  } catch {
+    throw new FunyardError('Unable to save secure config file.');
+  } finally {
+    await file?.close();
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+export async function readSecret(input = process.stdin, output = process.stderr) {
+  if (!input.isTTY || !input.setRawMode)
+    throw new FunyardError('Login requires an interactive terminal; for automation use FUNYARD_API_KEY.');
+  output.write('API key (hidden): ');
+  const wasRaw = input.isRaw;
+  input.setRawMode(true);
+  input.resume();
+  return new Promise((resolve, reject) => {
+    let secret = '';
+    const finish = error => {
+      input.off('data', onData);
+      input.off('end', onEnd);
+      input.setRawMode(wasRaw);
+      input.pause();
+      output.write('\n');
+      error ? reject(error) : resolve(secret);
+    };
+    const onEnd = () => finish(new FunyardError('Login input ended.'));
+    const onData = chunk => {
+      for (const char of chunk.toString('utf8')) {
+        if (char === '\u0003' || char === '\u0004') return finish(new FunyardError('Login cancelled.'));
+        if (char === '\r' || char === '\n') return finish();
+        if (char === '\u007f' || char === '\b') secret = secret.slice(0, -1);
+        else if (char >= ' ') secret += char;
+      }
+      if (secret.length > 8192) finish(new FunyardError('API key is too long.'));
+    };
+    input.on('data', onData);
+    input.once('end', onEnd);
+  });
+}