Call a third-party API from a Convex action, using the "use node" directive when needed and ctx.runQuery/ctx.runMutation to touch the database

Documented steps

1. Create convex/myActions.ts and import { action } from "./_generated/server" and { v } from "convex/values".
2. Store the third-party API key as a Convex environment variable: npx convex env set GIPHY_KEY 'xxx' (or set it in the Dashboard under Deployment Settings) rather than hardcoding it.
3. If the call needs Node.js-only APIs or npm packages unsupported by the Convex runtime, add the line "use node"; as the VERY FIRST line of the file; such a file may contain actions only.
4. Define the action: export const doSomething = action({ args: { a: v.number() }, handler: async (ctx, args) => { ... } }).
5. Inside the handler call the external service with fetch, e.g. fetch("https://api.thirdpartyservice.com?api_key=" + process.env.GIPHY_KEY); process.env.KEY returns a string or undefined.
6. Actions have no ctx.db, so read/write Convex data via ctx.runQuery(internal.module.readData, { a: args.a }) and ctx.runMutation(internal.module.writeData, { a: args.a }) targeting internalQuery/internalMutation functions.
7. Batch database access into as few runQuery/runMutation calls as possible; each call is its own separate transaction, so multiple sequential calls are NOT consistent with each other.
8. Use ctx.runAction(internal.module.otherAction, args) only when you must cross JS runtimes (e.g. a default-runtime action calling a "use node" action); otherwise call a plain shared helper function.
9. Await every promise created in the handler; dangling promises when the function returns may not complete and can cause errors on later invocations.
10. Deploy, then invoke the action from a client with useAction or from another Convex function.
11. Official docs: https://docs.convex.dev/functions/actions and https://docs.convex.dev/production/environment-variables