@kody/fly

import {
	API_TOKEN_SETUP_URL,
	FLY_API_HOST,
	FLY_GRAPHQL_URL,
	MACHINES_API_BASE_URL,
	MACHINES_HOST,
	MACHINES_OPENAPI_SPEC,
} from './fly-core.ts'

/**
 * Return Fly.io API patterns, auth notes, and export discovery metadata.
 */
export default async function docs() {
	return {
		package: '@kody/fly',
		publicUrl: 'https://kody.codes/@kody/fly',
		auth: {
			type: 'secret',
			secretName: 'flyApiToken',
			setupUrl: API_TOKEN_SETUP_URL,
			hosts: [MACHINES_HOST, FLY_API_HOST],
			notes:
				'Machines REST uses a Bearer token. GraphQL uses Bearer. App logs and Prometheus use FlyV1. There is no Fly OAuth path.',
		},
		api: {
			machinesOpenApi: MACHINES_OPENAPI_SPEC,
			machinesBaseUrl: MACHINES_API_BASE_URL,
			machinesOps: [
				'apps_list GET /apps?org_slug=',
				'apps_show GET /apps/{app_name}',
				'machines_list GET /apps/{app_name}/machines',
				'machines_show GET /apps/{app_name}/machines/{machine_id}',
				'machines_start POST /apps/{app_name}/machines/{machine_id}/start',
				'machines_stop POST /apps/{app_name}/machines/{machine_id}/stop',
				'machines_delete DELETE /apps/{app_name}/machines/{machine_id}',
				'machines_org_list GET /orgs/{org_slug}/machines',
				'currenttoken_show GET /tokens/current',
			],
			endpoint: FLY_GRAPHQL_URL,
			logsEndpoint: 'https://api.fly.io/api/v1/apps/:app/logs',
			prometheusEndpoint: 'https://api.fly.io/prometheus/:org/api/v1/query and /query_range',
		},
		mutations: {
			dryRun: 'Pass dryRun: true on startMachine, stopMachine, and destroyMachine.',
			confirm: 'destroyMachine also requires confirm: true.',
		},
		jobs: {
			'machine-status': 'Disabled by default. Read-only machine counts via ./scheduled-status.',
		},
		exports: {
			'.': 'Action dispatcher; defaults to smoke-test.',
			'./graphql': 'Run custom Fly GraphQL queries.',
			'./organizations': 'List or resolve organizations via GraphQL. No default org slug.',
			'./apps': 'List/get apps via Machines REST.',
			'./machines': 'List/get machines; start/stop/destroy with dryRun.',
			'./machine-count': 'Count machines and group by state/app.',
			'./app-machines': 'List machines for an app by appName or appId.',
			'./logs':
				'Fetch app logs by time window, normalize entries, return JSONL when requested, and summarize outage signals.',
			'./metrics':
				'Run Fly Prometheus instant/range queries and common app metrics for CPU, load, memory, disk, volumes, and edge HTTP responses.',
			'./smoke-test': 'Dry-run self-check plus optional live org/apps read.',
			'./scheduled-status': 'No-argument read-only machine-count wrapper for the disabled job.',
			'./docs': 'This discovery document.',
		},
	}
}