@lukoweb/apitogo 0.2.37 → 0.2.39

package/dist/cli/cli.js

@@ -6596,7 +6596,7 @@ function dependencyRules(config2, resolved, out) {
   const identityOn = resolved.identity?.enabled === true;
   const oidcGateway = gatewayOn && resolved.gateway?.auth?.mode === "oidc";
   const hasIdentitySource = identityOn || oidcGateway;
-  if (identityOn && resolved.portal?.enabled !== true && !gatewayOn) {
+  if (identityOn && resolved.portal?.enabled !== true && !gatewayOn && !resolved.project.id) {
     out.error({
       code: "NOTHING_TO_HOST",
       path: "identity",
@@ -7932,7 +7932,11 @@ function planPortal(profile, manifest) {
     plan2.plansPlugin = {
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
-      billing: plans.billing
+      billing: plans.billing,
+      links: {
+        ...profile.modules.docs ? { docs: "/introduction" } : profile.docs.url ? { docs: profile.docs.url } : {},
+        ...plan2.apiReference ? { api: `/${API_REFERENCE_PATH}` } : {}
+      }
     };
   }
   return plan2;
@@ -8634,7 +8638,7 @@ async function buildPlans(context) {
   const { options, dir, resolved } = context;
   const o = options.plans ?? {};
   const template = o.template ?? (options.template === "blank" ? "none" : options.template === "starter" ? "free" : "free");
-  const billing = o.billing ?? "stripe";
+  const billing = o.billing ?? (template === "tiered" ? "stripe" : "none");
   if (template === "tiered" && billing === "none") {
     throw new ServiceEditError(
       "The tiered template has paid plans, which need a billing provider.",
@@ -9731,6 +9735,16 @@ var PlatformApiClient = class {
       `/api/v1/projects/${projectId}/gateway/plans/${planId}`
     );
   }
+  /**
+   * For test runs only: puts the project's plans backend back to empty (accounts, subscriptions, keys, cached catalogs).
+   * Answers 404 unless the platform has the test tools on and the project is a `tester-` project.
+   */
+  resetDevPortalTestData(projectId) {
+    return this.request(
+      "POST",
+      `/api/v1/projects/${projectId}/dev-portal/test-reset`
+    );
+  }
   /**
    * For test runs only: a test user and a one-time sign-in link for it. The platform answers 404 unless it allows test
    * tools and the project is a `tester-` project.
@@ -10073,7 +10087,7 @@ import {
 // package.json
 var package_default = {
   name: "@lukoweb/apitogo",
-  version: "0.2.37",
+  version: "0.2.39",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -15095,6 +15109,14 @@ function capabilityIssues(gateway, answer) {
       );
   return found;
 }
+function pendingIdentityNote(item, state) {
+  if (item.code !== "GATEWAY_AUTH_INCOMPLETE" || !state.identityEnabled || state.identityDeployed)
+    return void 0;
+  return {
+    ...item,
+    message: `${item.message} The identity is made by the first deploy, before the gateway, so this is expected until then.`
+  };
+}
 async function onlineGatewayRules(gateway, projectId, api, derivedCors = []) {
   let spec;
   const specFile = gateway.specs[0];
@@ -15413,7 +15435,12 @@ async function addGatewayOnlineRules(report, resolved, args, deps) {
     const key = `${item.code}|${item.path}`;
     if (seen.has(key)) continue;
     seen.add(key);
-    report.errors.push(item);
+    const pending = pendingIdentityNote(item, {
+      identityEnabled: resolved.identity?.enabled === true,
+      identityDeployed: manifest?.services.identity !== void 0
+    });
+    if (pending) report.warnings.push(pending);
+    else report.errors.push(item);
   }
   return true;
 }
@@ -26983,6 +27010,18 @@ function describePlatformProblem(error) {
     )
   ] : [];
 }
+async function withServerRetry(request, sleep5, waitsMs = [5e3, 15e3]) {
+  for (const wait of waitsMs) {
+    try {
+      return await request();
+    } catch (error) {
+      if (!(error instanceof PlatformApiError) || error.status < 500)
+        throw error;
+      await sleep5(wait);
+    }
+  }
+  return request();
+}
 function rejected(what, error) {
   if (error instanceof PlatformApiError && error.status === 400) {
     const lines = describePlatformProblem(error);
@@ -27002,7 +27041,7 @@ async function deployGateway(resolved, projectId, deps, options = {}) {
   const client = deps.client;
   const sleep5 = deps.sleep ?? defaultSleep;
   const now = deps.now ?? Date.now;
-  const timeoutMs = deps.reconcileTimeoutMs ?? 18e4;
+  const timeoutMs = deps.reconcileTimeoutMs ?? 42e4;
   const backendTimeoutMs = deps.backendTimeoutMs ?? 20 * 6e4;
   const intervalMs = deps.pollIntervalMs ?? 2e3;
   const backendStep = {
@@ -27070,7 +27109,10 @@ async function deployGateway(resolved, projectId, deps, options = {}) {
     hash: () => specHash,
     run: async () => {
       try {
-        const uploaded = await client.putGatewaySpec(projectId, spec);
+        const uploaded = await withServerRetry(
+          () => client.putGatewaySpec(projectId, spec),
+          sleep5
+        );
         return {
           specSha256: uploaded.sha256,
           operationCount: String(uploaded.operationCount)
@@ -27086,7 +27128,10 @@ async function deployGateway(resolved, projectId, deps, options = {}) {
     hash: () => configHash,
     run: async () => {
       try {
-        const accepted = await client.putGatewayConfig(projectId, body);
+        const accepted = await withServerRetry(
+          () => client.putGatewayConfig(projectId, body),
+          sleep5
+        );
         return {
           reconciliationId: accepted.reconciliationId,
           desiredHash: accepted.desiredHash
@@ -27095,13 +27140,17 @@ async function deployGateway(resolved, projectId, deps, options = {}) {
         return rejected("gateway config", error);
       }
     },
-    // A reconciliation the platform gave up on is not a result worth keeping.
+    // A reconciliation the platform gave up on is not a result worth keeping, and neither is one for a gateway that was
+    // removed since (a reset, a teardown, or the web app): the records here would say "deployed" for a gateway that is gone.
     stillValid: async () => {
       const ticket = await ticketOf();
       if (!ticket) return false;
       try {
         const state = await client.getGatewayReconciliation(projectId, ticket);
-        return state.state !== "Failed" && state.state !== "Superseded";
+        if (state.state === "Failed" || state.state === "Superseded")
+          return false;
+        const gateway2 = await client.getGatewayStatus(projectId);
+        return gateway2.status !== "Released";
       } catch {
         return false;
       }
@@ -27132,7 +27181,7 @@ async function deployGateway(resolved, projectId, deps, options = {}) {
           throw new GatewayDeployError(
             "GATEWAY_RECONCILE_TIMEOUT",
             `The platform did not finish within ${Math.round(timeoutMs / 1e3)} seconds (state: ${state.state}).`,
-            "Run deploy again to keep waiting. If it stays Pending, the platform worker that applies gateway configs may not be running yet."
+            "The gateway is still being made: run deploy again to keep waiting (a gateway made just after a reset takes the longest). If it stays Pending for many minutes, the platform worker that applies gateway configs may not be running."
           );
         await sleep5(intervalMs);
       }
@@ -27263,6 +27312,14 @@ function referencedSecretNames(connections) {
     )
   ];
 }
+function identityProviderSwitch(resolved, known) {
+  if (!known?.provider || !resolved.identity) return void 0;
+  const to = resolved.identity.provider ?? "apitogo";
+  return known.provider === to ? void 0 : { from: known.provider, to };
+}
+function identityProviderSwitchWarning(from, to) {
+  return `warning: the identity provider changes from ${from} to ${to}. People are known by issuer and subject, so the users, subscriptions and keys made with ${from} are not carried over to ${to}.`;
+}
 var PORTAL_CALLBACK_PATH = "/oauth/callback";
 var defaultSleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function identityNotDeployableReason(resolved) {
@@ -27294,7 +27351,7 @@ async function portalUrlOf(resolved, projectId, client) {
     throw new IdentityDeployError(
       "IDENTITY_PORTAL_ADDRESS_UNKNOWN",
       "The portal has no public address yet, and the identity needs it for the sign-in redirect.",
-      "Run `apitogo deploy --only portal` once so the platform gives the portal an address, then deploy identity."
+      "The address comes with the project's hosting. Run `apitogo status`: while hosting is still being prepared, wait a few minutes and run `apitogo deploy` again. Once hosting is ready, `apitogo deploy --only portal` gives the portal its address, then deploy identity."
     );
   return url2;
 }
@@ -27712,11 +27769,15 @@ async function deployPlans(resolved, projectId, deps, options = {}) {
       let created = 0;
       let updated = 0;
       let archived = 0;
+      const backendSync = /* @__PURE__ */ new Set();
+      const noteSync = (plan2) => {
+        if (plan2.plansBackendSync) backendSync.add(plan2.plansBackendSync);
+      };
       for (const body of bodies) {
         const found = existing.get(body.sku);
         try {
           if (found) {
-            await client.updateGatewayPlan(projectId, found.id, {
+            const result = await client.updateGatewayPlan(projectId, found.id, {
               displayName: body.displayName,
               isActive: true,
               limitsJson: body.limitsJson ?? null,
@@ -27728,9 +27789,10 @@ async function deployPlans(resolved, projectId, deps, options = {}) {
               billingPeriod: body.billingPeriod,
               sortOrder: body.sortOrder
             });
+            noteSync(result);
             updated++;
           } else {
-            await client.createGatewayPlan(projectId, body);
+            noteSync(await client.createGatewayPlan(projectId, body));
             created++;
           }
         } catch (error) {
@@ -27741,7 +27803,7 @@ async function deployPlans(resolved, projectId, deps, options = {}) {
       for (const plan2 of existing.values()) {
         if (!plan2.isActive || kept.has(plan2.sku.toLowerCase())) continue;
         try {
-          await client.updateGatewayPlan(projectId, plan2.id, {
+          const result = await client.updateGatewayPlan(projectId, plan2.id, {
             displayName: plan2.displayName,
             isActive: false,
             limitsJson: plan2.limitsJson ?? null,
@@ -27754,6 +27816,7 @@ async function deployPlans(resolved, projectId, deps, options = {}) {
             billingPeriod: plan2.billingPeriod,
             sortOrder: plan2.sortOrder
           });
+          noteSync(result);
           archived++;
         } catch (error) {
           refused(error);
@@ -27762,7 +27825,8 @@ async function deployPlans(resolved, projectId, deps, options = {}) {
       return {
         created: String(created),
         updated: String(updated),
-        archived: String(archived)
+        archived: String(archived),
+        ...backendSync.size > 0 ? { backendSync: [...backendSync].sort().join(",") } : {}
       };
     },
     // A plan someone deleted on the platform is not a result worth keeping, and neither is one that should be
@@ -27934,6 +27998,8 @@ async function planIdentityService(resolved, ledger, manifest) {
       details: []
     };
   const known = manifest?.services.identity;
+  const switched = identityProviderSwitch(resolved, known);
+  const switchNote = switched ? [identityProviderSwitchWarning(switched.from, switched.to)] : [];
   if (identity.provider === "oidc") {
     const same = known?.provider === "oidc" && known.issuer === identity.issuer?.replace(/\/+$/, "") && known.clientId === identity.clientId;
     return {
@@ -27941,6 +28007,7 @@ async function planIdentityService(resolved, ledger, manifest) {
       action: same ? "skip" : "deploy",
       reason: same ? "deploy skipped: services.json already records your sign-in provider" : "will record your own sign-in provider in services.json (nothing is made on the platform)",
       details: [
+        ...switchNote,
         `provider: oidc ${identity.issuer}`,
         `client id: ${identity.clientId}`
       ]
@@ -27952,6 +28019,7 @@ async function planIdentityService(resolved, ledger, manifest) {
   const body = portalUrl ? identityRequestBody(resolved, portalUrl) : recorded ? identityBodyForRedirect(resolved, recorded) : void 0;
   const hash2 = projectId && body ? identityInputsHash(projectId, body) : void 0;
   const details = [
+    ...switchNote,
     "provider: apitogo (one issuer for this project)",
     `sign-up with email and password: ${identity.native ? "on" : "off"}`,
     portalUrl ? `sign-in redirect: ${portalUrl.replace(/\/+$/, "")}${PORTAL_CALLBACK_PATH}` : recorded ? `sign-in redirect: ${recorded} (sent by the last deploy)` : "sign-in redirect: the portal address is not known locally; deploy takes it from the project",
@@ -28559,6 +28627,20 @@ async function gatewayStatus(resolved, ledger, manifest, remote) {
   if (failed) state = "deploy-failed";
   return { service: "gateway", state, details: [...details, ...local] };
 }
+async function hostingLine(resolved, manifest, remote) {
+  const projectId = resolved.project.id ?? manifest?.project.id;
+  if (!remote || !projectId) return [];
+  try {
+    const address = await remote(projectId);
+    return address ? [`hosting: ready (${address})`] : [
+      "hosting: not ready yet (the platform is still preparing it; wait a few minutes, then run `apitogo deploy`)"
+    ];
+  } catch (error) {
+    return [
+      `hosting: not reachable (${error instanceof Error ? error.message : String(error)})`
+    ];
+  }
+}
 async function wantedSkus(resolved) {
   if (!resolved.plans) return void 0;
   try {
@@ -28601,7 +28683,8 @@ async function statusV2(dir, only, options = {}) {
           ...state === "built" ? [
             `output: ${path82.relative(resolved.configDir, resolved.state.buildDir)}`
           ] : [],
-          ...url2 ? [`url: ${url2}`] : ["url: not known (portal is not deployed yet)"]
+          ...url2 ? [`url: ${url2}`] : ["url: not known (portal is not deployed yet)"],
+          ...await hostingLine(resolved, manifest, options.hostingRemote)
         ]
       });
       continue;
@@ -28719,6 +28802,12 @@ function parseDeployOnly(value) {
   }
   return DEPLOY_ORDER.filter((name) => names.includes(name));
 }
+function isHostingNotReady(error) {
+  if (!(error instanceof PlatformApiError)) return false;
+  return /not provisioned yet|Could not retrieve deployment token/i.test(
+    `${error.message} ${error.problem?.detail ?? ""}`
+  );
+}
 function publishStep(deps, options) {
   return {
     name: "publish",
@@ -28738,6 +28827,14 @@ function publishStep(deps, options) {
           byteSize: String(upload.byteSize),
           deployServerStatus: String(upload.deployServerStatus)
         };
+      } catch (error) {
+        if (isHostingNotReady(error))
+          throw new DeployError(
+            "HOSTING_NOT_READY",
+            "The portal's hosting is not ready yet: the platform is still preparing it, so there is nothing to publish to.",
+            "Nothing is wrong with your files. Run `apitogo status` to see the hosting, wait a few minutes (a project made while the pool was full waits longest), then run `apitogo deploy` again."
+          );
+        throw error;
       } finally {
         await rm11(archive.archivePath, { force: true });
       }
@@ -28865,6 +28962,16 @@ async function deployIdentityService(options, deps, projectId, named) {
       );
     return { service: "identity", status: "skipped", reason: why, steps: [] };
   }
+  const switched = identityProviderSwitch(
+    resolved,
+    (await readManifest(resolved.state))?.services.identity
+  );
+  if (switched && options.yes !== true)
+    throw new DeployError(
+      "CONFIRMATION_REQUIRED",
+      identityProviderSwitchWarning(switched.from, switched.to),
+      "`apitogo plan` shows it too. Run `apitogo deploy --yes` to go on."
+    );
   const client = deps.client;
   if (resolved.identity?.provider !== "oidc" && (!client.putProjectIdentity || !client.getProjectIdentity || !client.getProject))
     throw new Error("The platform client has no identity calls.");
@@ -28916,7 +29023,26 @@ async function deployPlansService(options, deps, projectId, named) {
     ...result.notes ? { notes: result.notes } : {}
   };
 }
+async function recordPortalAddressBeforeBuild(dir, deps, projectId) {
+  const { resolved } = loadConfigV2(dir);
+  if (!resolved.portal?.enabled) return;
+  const manifest = await readManifest(resolved.state);
+  if (manifest?.services.portal?.url) return;
+  const url2 = resolveSwaUrl(await deps.client.getProject(projectId));
+  if (!url2) return;
+  const profile = portalProfile(resolved);
+  await writeManifest(
+    resolved.state,
+    withPortalEntry(manifest, {
+      projectId,
+      projectName: resolved.project.name,
+      url: url2,
+      docs: { provider: profile.docs.provider, url: profile.docs.url }
+    })
+  );
+}
 async function deployPortal(options, deps, projectId) {
+  await recordPortalAddressBeforeBuild(options.dir, deps, projectId);
   const { resolved, root, prepared } = await preparePortalWorkspace(
     options.dir,
     "production"
@@ -29000,6 +29126,7 @@ async function deployProject(argv) {
         projectId: argv.projectId,
         env: argv.env,
         force: argv.force === true,
+        yes: argv.yes === true,
         jsonOnly: json
       },
       {
@@ -29062,6 +29189,11 @@ var deploy_default = {
     type: "boolean",
     describe: "Force redeploy of selected resources even when healthy",
     default: false
+  }).option("yes", {
+    alias: "y",
+    type: "boolean",
+    describe: "Config version 2: confirm a change that cannot be undone, such as switching the identity provider",
+    default: false
   }).option("resume-from", {
     type: "string",
     describe: "Resume publish ledger from step id"
@@ -29502,10 +29634,19 @@ function plansRemote() {
     return void 0;
   }
 }
+function hostingRemote() {
+  try {
+    const client = new PlatformApiClient(loadConfig());
+    return async (projectId) => resolveSwaUrl(await client.getProject(projectId));
+  } catch {
+    return void 0;
+  }
+}
 var statusOfProject = (argv) => run2(
   "status",
   argv,
   (dir, only) => statusV2(dir, only, {
+    hostingRemote: hostingRemote(),
     gatewayRemote: gatewayRemote(),
     identityRemote: identityRemote(),
     identityConnectionsRemote: identityConnectionsRemote(),
@@ -29647,7 +29788,7 @@ async function createProjectV2(options, deps) {
     throw new ProjectCreateError(
       "CREATE_FAILED",
       "The project was created but hosting is still being prepared.",
-      `The folder is linked (project.id ${outcome.projectId}). Wait a few minutes, then run \`apitogo deploy\`.`
+      `The folder is linked (project.id ${outcome.projectId}). Wait a few minutes (hosting takes 20 to 30 minutes, longer while the pool is full), then run \`apitogo project create\` again: it finishes the same project and does not make a second one. \`apitogo status\` shows how far it is.`
     );
   }
   await setProjectId(options.dir, outcome.projectId);
@@ -29664,7 +29805,7 @@ function assertCreated(outcome) {
     throw new ProjectCreateError(
       "CREATE_FAILED",
       `The platform could not create the project: ${outcome.message ?? outcome.status ?? "no answer"}.`,
-      "Nothing was written to this folder. Try again, or check `apitogo status`."
+      /capacity/i.test(outcome.message ?? "") ? "There is no free hosting right now. Run `apitogo project create` again in a few minutes: it picks up where it stopped, and a project that was already made is not made twice. `apitogo status` shows whether this folder is linked." : "Try again, or check `apitogo status`."
     );
   }
 }
@@ -31294,10 +31435,11 @@ async function resetProjectV2(options, deps) {
       "Resetting removes the plans, the identity with every user, and the gateway of the project.",
       "Pass --yes to go on."
     );
+  const sleep5 = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const steps = [];
   for (const service of STEPS) {
     try {
-      const result = await teardownV2(
+      const removeOnce = () => teardownV2(
         {
           dir: options.dir,
           projectId,
@@ -31307,6 +31449,12 @@ async function resetProjectV2(options, deps) {
         },
         deps
       );
+      const result = await removeOnce().catch(async (error) => {
+        if (!(error instanceof PlatformApiError) || error.status < 500)
+          throw error;
+        await sleep5(5e3);
+        return removeOnce();
+      });
       if (result.status === "pending") {
         steps.push({ service, outcome: "pending", message: result.message });
         return {
@@ -31315,6 +31463,7 @@ async function resetProjectV2(options, deps) {
           status: "pending",
           steps,
           cleared: [],
+          notes: [],
           message: `The ${service} is still being removed by the platform. Run the reset again in a minute.`
         };
       }
@@ -31327,6 +31476,22 @@ async function resetProjectV2(options, deps) {
       throw error;
     }
   }
+  let backendNote;
+  if (deps.client.resetDevPortalTestData) {
+    const emptyOnce = async () => {
+      try {
+        return (await deps.client.resetDevPortalTestData?.(projectId))?.plansBackend ?? "no-answer";
+      } catch (error) {
+        return `failed-${error instanceof Error ? error.message : String(error)}`;
+      }
+    };
+    let outcome = await emptyOnce();
+    if (outcome.startsWith("failed") || /^refused-5/.test(outcome)) {
+      await sleep5(15e3);
+      outcome = await emptyOnce();
+    }
+    backendNote = outcome === "notified" ? "plans backend: emptied" : outcome === "no-backend" ? "plans backend: nothing to empty yet (the project has none)" : `plans backend: not emptied (${outcome})`;
+  }
   const cleared = [];
   const ledger = await readLedger(resolved.state);
   const recorded = DEPLOY_ORDER.filter((service) => ledger.services[service]);
@@ -31342,6 +31507,7 @@ async function resetProjectV2(options, deps) {
     status: "reset",
     steps,
     cleared,
+    notes: backendNote ? [backendNote] : [],
     message: "The project is reset: it is linked and its hosting is kept. Run `apitogo deploy` to build on it again."
   };
 }
@@ -31371,7 +31537,10 @@ async function resetProject(argv) {
       return;
     }
     for (const step2 of result.steps)
-      console.log(`${step2.service}: ${step2.outcome}`);
+      console.log(
+        `${step2.service}: ${step2.outcome}${step2.outcome === "skipped" ? " (nothing was deployed)" : ""}`
+      );
+    for (const note of result.notes) console.log(note);
     if (result.cleared.length > 0)
       console.log(`Cleared locally: ${result.cleared.join(", ")}.`);
     console.log(result.message);

package/dist/declarations/cli/platform/client/platform-api.d.ts

@@ -108,6 +108,7 @@ export interface GatewayPlanDto {
     priceAmount?: number;
     pricingModel?: "fixed" | "custom";
     priceLabel?: string | null;
+    plansBackendSync?: string | null;
     priceCurrency?: string;
     billingPeriod?: string;
     limitsJson?: string | null;
@@ -598,6 +599,9 @@ export declare class PlatformApiClient {
     getGatewayPlan(projectId: string, planId: string): Promise<GatewayPlanDto>;
     updateGatewayPlan(projectId: string, planId: string, body: UpdateGatewayPlanRequest): Promise<GatewayPlanDto>;
     deleteGatewayPlan(projectId: string, planId: string): Promise<void>;
+    resetDevPortalTestData(projectId: string): Promise<{
+        plansBackend: string;
+    }>;
     createTestSignIn(projectId: string, body: {
         email: string;
         returnUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/rules.ts

@@ -73,8 +73,14 @@ function dependencyRules(
   const oidcGateway = gatewayOn && resolved.gateway?.auth?.mode === "oidc";
   const hasIdentitySource = identityOn || oidcGateway;
 
-  // `apitogo project create` hosts services through the portal or the gateway, so identity alone has nowhere to run.
-  if (identityOn && resolved.portal?.enabled !== true && !gatewayOn) {
+  // `apitogo project create` hosts services through the portal or the gateway, so identity alone has nowhere to run. A folder
+  // that is already linked to a project has its hosting, and `deploy` puts the identity there (found in scenario F).
+  if (
+    identityOn &&
+    resolved.portal?.enabled !== true &&
+    !gatewayOn &&
+    !resolved.project.id
+  ) {
     out.error({
       code: "NOTHING_TO_HOST",
       path: "identity",

package/src/config/v2/services.ts

@@ -313,10 +313,10 @@ async function buildPortal(
     if (content.length === 0) {
       let template = options.template;
       if (!template && options.ask)
-        template = await options.ask.choose("Content of the new site", [
+        template = (await options.ask.choose("Content of the new site", [
           { value: "starter", label: "A starter page I can edit" },
           { value: "blank", label: "An empty pages folder" },
-        ]);
+        ])) as "starter" | "blank";
       const pages = path.join(resolved.root, "portal", "pages");
       if (template === "blank")
         await addFile(context, path.join(pages, ".gitkeep"), "");
@@ -579,7 +579,9 @@ async function buildPlans(
       : options.template === "starter"
         ? "free"
         : "free");
-  const billing = o.billing ?? "stripe";
+  // Only paid plans need a billing provider. A catalog of free plans takes no payment, so its default is `none` and the
+  // config checks clean right away; the tiered template (paid plans) defaults to Stripe, whose key is set with `secrets set`.
+  const billing = o.billing ?? (template === "tiered" ? "stripe" : "none");
   if (template === "tiered" && billing === "none") {
     throw new ServiceEditError(
       "The tiered template has paid plans, which need a billing provider.",

package/src/config/v2/wrapper.ts

@@ -68,6 +68,8 @@ export type PortalPlan = {
     keysApiBaseUrl?: string;
     /** The billing provider of the plans service (`none`, `stripe`, ...). `none`: the pages offer no payment. */
     billing?: string;
+    /** Where the account pages link to: only places this portal has (hosted docs, an external docs site, the API page). */
+    links?: { docs?: string; api?: string };
   };
   /** Account pages. */
   userPanel: boolean;
@@ -231,6 +233,14 @@ export function planPortal(
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
       billing: plans.billing,
+      links: {
+        ...(profile.modules.docs
+          ? { docs: "/introduction" }
+          : profile.docs.url
+            ? { docs: profile.docs.url }
+            : {}),
+        ...(plan.apiReference ? { api: `/${API_REFERENCE_PATH}` } : {}),
+      },
     };
   }