@kody/twilio

import {
	API_HOST,
	DEFAULT_ACCOUNT_SID_SECRET,
	DEFAULT_AUTH_TOKEN_SECRET,
	accountSidSetupUrl,
	authTokenSetupUrl,
	resolveAccountSidSecretName,
	resolveAuthTokenSecretName,
	type TwilioAuthOptions,
} from './validation.ts'

/** Agent-usable setup URLs and Twilio console steps for this package. */
export default async function guide(params: TwilioAuthOptions = {}) {
	const accountSidSecret = resolveAccountSidSecretName(params)
	const authTokenSecret = resolveAuthTokenSecretName(params)
	return {
		auth: 'account-sid-auth-token',
		oauth: false,
		requiredHosts: [API_HOST],
		secrets: {
			accountSid: accountSidSecret,
			authToken: authTokenSecret,
		},
		secretUrls: {
			accountSid: accountSidSetupUrl(accountSidSecret),
			authToken: authTokenSetupUrl(authTokenSecret),
		},
		docs: 'https://www.twilio.com/docs/iam/api-keys',
		console: 'https://console.twilio.com',
		steps: [
			'Open the Twilio Console and copy the Account SID and Auth Token from the account dashboard.',
			'Never paste those values into chat.',
			'Save the Account SID at the accountSid secret URL and approve host api.twilio.com.',
			'Save the Auth Token at the authToken secret URL and approve host api.twilio.com.',
			'Optional: after forking, store a Messaging Service SID in packageStorage via ./config (no phone numbers belong in package source).',
			'Invoke kody:@kody/twilio/smoke-test to verify account lookup.',
			'send-message defaults to dryRun. A live SMS requires confirm: true after explicit user approval of to, from/Messaging Service, and body.',
		],
		multiAccount:
			'Default secrets are twilioAccountSid and twilioAuthToken. Additional accounts use account: "work" (secrets twilioAccountSid-work / twilioAuthToken-work).',
		defaultSecretNames: {
			accountSid: DEFAULT_ACCOUNT_SID_SECRET,
			authToken: DEFAULT_AUTH_TOKEN_SECRET,
		},
	}
}