@cardstack/boxel-cli 0.12.0-unstable.13 → 0.12.0-unstable.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardstack/boxel-cli",
-  "version": "0.12.0-unstable.13",
+  "version": "0.12.0-unstable.14",
   "license": "MIT",
   "description": "CLI tools for Boxel workspace management",
   "main": "./dist/index.js",

package/src/commands/keys/approve.ts

@@ -25,6 +25,7 @@ import {
   type WindowOutcome,
 } from '../../lib/sso-login.ts';
 import {
+  anonymousCapsClause,
   findUserKey,
   listOwnShares,
   type UserKeyGrant,
@@ -372,7 +373,7 @@ function printBatch(
       say(
         ctx,
         share.anonymous
-          ? `  ${FG_YELLOW}Anyone on the internet who opens this card, including people who aren't signed in, can make ${operations.join(', ')} with ${share.label}${share.anonymousDailyCap != null ? `, up to ${share.anonymousDailyCap} calls a day all together` : ''}.${RESET}`
+          ? `  ${FG_YELLOW}Anyone on the internet who opens this card, including people who aren't signed in, can make ${operations.join(', ')} with ${share.label}${anonymousCapsClause(share)}.${RESET}`
           : `  This realm lets people who aren't signed in make ${operations.join(', ')}, but ${share.label}'s key allows signed-in people only, so they're asked to sign in.`,
       );
     }

package/src/commands/keys/index.ts

@@ -178,12 +178,17 @@ export function registerKeysCommand(program: Command): void {
       '--anonymous-cap <calls>',
       "With --anonymous, the most calls a day people who aren't signed in make with it, all together, in every realm it's shared into",
     )
+    .option(
+      '--anonymous-monthly-cap <calls>',
+      "With --anonymous, the most calls a UTC month people who aren't signed in make with it, all together, in every realm it's shared into",
+    )
     .action(
       (
         name: string,
         options: ValueCommandOptions & {
           anonymous?: boolean;
           anonymousCap?: string;
+          anonymousMonthlyCap?: string;
         },
       ) => runKeysCommand(options.json, () => keysAdd(name, options)),
     );
@@ -191,20 +196,24 @@ export function registerKeysCommand(program: Command): void {
   keys
     .command('anonymous')
     .description(
-      "Say whether people who aren't signed in may use one of your keys, wherever a realm you share it into lets them make the call. off clears the cap",
+      "Say whether people who aren't signed in may use one of your keys, wherever a realm you share it into lets them make the call. off clears both caps; on keeps a cap you don't name",
     )
     .argument('<name>', 'The key')
     .argument('<on|off>', 'Allow it or not')
     .option(
       '--cap <calls>',
-      "With on, the most calls a day people who aren't signed in make with it, all together, in every realm it's shared into",
+      "With on, the most calls a day people who aren't signed in make with it, all together, in every realm it's shared into, or none to remove the cap",
+    )
+    .option(
+      '--monthly-cap <calls>',
+      "With on, the most calls a UTC month people who aren't signed in make with it, all together, in every realm it's shared into, or none to remove the cap",
     )
     .option('--json', 'Output JSON')
     .action(
       (
         name: string,
         setting: string,
-        options: { cap?: string; json?: boolean },
+        options: { cap?: string; monthlyCap?: string; json?: boolean },
       ) =>
         runKeysCommand(options.json, () =>
           keysAnonymous(name, setting, options),

package/src/commands/keys/manage.ts

@@ -40,6 +40,7 @@ import {
   replaceUserKey,
   setKeyLimits,
   setUserKeyAnonymousUse,
+  anonymousCapsClause,
   shareUserKey,
   completeOAuthConnect,
   startOAuthConnect,
@@ -605,6 +606,7 @@ export async function keysAdd(
     json?: boolean;
     anonymous?: boolean;
     anonymousCap?: string;
+    anonymousMonthlyCap?: string;
   } & KeyValueSource &
     ServiceAccountOptions &
     OAuthClientOptions &
@@ -612,10 +614,13 @@ export async function keysAdd(
 ): Promise<UserKeyMetadata> {
   let ctx = context(options.json, options);
   let kind = options.kind ?? 'static';
-  let anonymousDailyCap = anonymousCapOption(
-    options.anonymous,
-    options.anonymousCap,
-  );
+  // A new key has no cap to remove, so these take numbers only.
+  let anonymousDailyCap =
+    anonymousCapOption(options.anonymous, options.anonymousCap) ?? undefined;
+  let anonymousMonthlyCap =
+    anonymousCapOption(options.anonymous, options.anonymousMonthlyCap, {
+      flag: '--anonymous-monthly-cap',
+    }) ?? undefined;
   if (options.anonymous && kind === 'oauth-client') {
     throw new Error(
       "--anonymous isn't taken when adding an OAuth client: a sign-in app's people each connect their own account, so it never serves people who aren't signed in. For one that gets its own tokens (client_credentials), allow it after adding: `boxel keys anonymous <name> on`",
@@ -636,6 +641,7 @@ export async function keysAdd(
     ...oauthClientSettings(kind, options),
     ...(options.anonymous ? { anonymous: true } : {}),
     ...(anonymousDailyCap !== undefined ? { anonymousDailyCap } : {}),
+    ...(anonymousMonthlyCap !== undefined ? { anonymousMonthlyCap } : {}),
   });
   emit(ctx, key, () => {
     if (kind === 'oauth-client' && options.grantType !== 'client_credentials') {
@@ -826,31 +832,42 @@ async function warnWhereVisitorsWillUse(
   }
   if (!key.anonymous) {
     throw new Error(
-      `${realm} lets people who aren't signed in make calls that send a shared key, so ${doing} ${name} there means they will use it, and ${name} doesn't allow them. To put it there, allow it for the key first: \`boxel keys anonymous ${name} on\` (with an optional --cap <calls>)`,
+      `${realm} lets people who aren't signed in make calls that send a shared key, so ${doing} ${name} there means they will use it, and ${name} doesn't allow them. To put it there, allow it for the key first: \`boxel keys anonymous ${name} on\` (with an optional --cap <calls> a day and --monthly-cap <calls> a month)`,
     );
   }
   console.error(
-    `${FG_YELLOW}Warning: ${doing} ${name} into ${realm} means people who aren't signed in will use it. The realm's policy lets anyone on the internet who opens its cards make calls that send a shared key, and read the responses. Their calls count against your quota and/or are billed to your account with the service${key.anonymousDailyCap != null ? `, up to ${key.anonymousDailyCap} calls a day all together` : ''}.${RESET}`,
+    `${FG_YELLOW}Warning: ${doing} ${name} into ${realm} means people who aren't signed in will use it. The realm's policy lets anyone on the internet who opens its cards make calls that send a shared key, and read the responses. Their calls count against your quota and/or are billed to your account with the service${anonymousCapsClause(key)}.${RESET}`,
   );
   return true;
 }
 
-// `--anonymous-cap <calls>`, given only with `--anonymous` (or `on`): a whole
-// number of calls a day, from 1.
+// An anonymous cap (`--anonymous-cap`, `--anonymous-monthly-cap`, or `--cap`
+// and `--monthly-cap` with `on`), given only with `--anonymous` (or `on`): a
+// whole number of calls, from 1. With `on`, `none` removes that cap (null)
+// and keeps anonymous use on.
 function anonymousCapOption(
   anonymous: boolean | undefined,
   cap: string | undefined,
-  { flag = '--anonymous-cap', with: withFlag = '--anonymous' } = {},
-): number | undefined {
+  {
+    flag = '--anonymous-cap',
+    with: withFlag = '--anonymous',
+    removable = false,
+  } = {},
+): number | null | undefined {
   if (cap === undefined) {
     return undefined;
   }
   if (!anonymous) {
     throw new Error(`${flag} is given with ${withFlag}`);
   }
+  if (removable && cap.trim().toLowerCase() === 'none') {
+    return null;
+  }
   let calls = Number(cap);
   if (!/^\d+$/.test(cap.trim()) || calls < 1 || calls > 2_147_483_647) {
-    throw new Error(`${flag} is a whole number of calls, from 1 to 2147483647`);
+    throw new Error(
+      `${flag} is a whole number of calls, from 1 to 2147483647${removable ? ', or none' : ''}`,
+    );
   }
   return calls;
 }
@@ -858,18 +875,22 @@ function anonymousCapOption(
 // How a key's setting for people who aren't signed in reads.
 function anonymousUseOf(key: UserKeyMetadata): string {
   return key.anonymous
-    ? `allowed${key.anonymousDailyCap != null ? `, up to ${key.anonymousDailyCap} calls a day all together` : ''}, wherever a realm's policy lets them make the call`
+    ? `allowed${anonymousCapsClause(key)}, wherever a realm's policy lets them make the call`
     : 'not allowed';
 }
 
 // Whether people who aren't signed in may use one of the user's keys: its
 // owner's setting for the key itself, which every realm it is shared into
-// follows where that realm's policy lets them make the call. `off` clears the
-// cap.
+// follows where that realm's policy lets them make the call. `off` clears
+// both caps; `on` keeps a cap it doesn't name, and removes one named `none`.
 export async function keysAnonymous(
   name: string,
   setting: string,
-  options: { cap?: string; json?: boolean } & KeysCommandDeps = {},
+  options: {
+    cap?: string;
+    monthlyCap?: string;
+    json?: boolean;
+  } & KeysCommandDeps = {},
 ): Promise<UserKeyMetadata> {
   if (setting !== 'on' && setting !== 'off') {
     throw new Error('say on or off');
@@ -878,6 +899,12 @@ export async function keysAnonymous(
   let anonymousDailyCap = anonymousCapOption(anonymous, options.cap, {
     flag: '--cap',
     with: 'on',
+    removable: true,
+  });
+  let anonymousMonthlyCap = anonymousCapOption(anonymous, options.monthlyCap, {
+    flag: '--monthly-cap',
+    with: 'on',
+    removable: true,
   });
   let ctx = context(options.json, options);
   let token = await secureToken(ctx);
@@ -886,6 +913,7 @@ export async function keysAnonymous(
     keyId: key.id,
     anonymous,
     ...(anonymousDailyCap !== undefined ? { anonymousDailyCap } : {}),
+    ...(anonymousMonthlyCap !== undefined ? { anonymousMonthlyCap } : {}),
   });
   emit(ctx, updated, () => {
     console.log(

package/src/lib/key-bindings.ts

@@ -97,9 +97,10 @@ export interface BatchShare {
   covers: string[];
   interactive: boolean;
   dailyBudget: number;
-  // Whether the share's key allows people who aren't signed in, and its cap.
+  // Whether the share's key allows people who aren't signed in, and its caps.
   anonymous?: boolean;
   anonymousDailyCap?: number | null;
+  anonymousMonthlyCap?: number | null;
 }
 
 export interface ApprovalBatch {

package/src/lib/user-keys.ts

@@ -100,10 +100,35 @@ export interface UserKeyMetadata {
   createdAt: string;
   updatedAt: string;
   // Whether its owner lets people who aren't signed in use it, wherever a
-  // realm's policy lets them make the call, and the optional cap on their
-  // calls a day, all together, in every realm it is shared into.
+  // realm's policy lets them make the call, and the optional caps on their
+  // calls a day and a month, all together, in every realm it is shared into.
   anonymous?: boolean;
   anonymousDailyCap?: number | null;
+  anonymousMonthlyCap?: number | null;
+}
+
+// A key's anonymous caps as a clause that ends a sentence about people who
+// aren't signed in: ", up to 100 calls a day and 1000 a month all together",
+// or nothing where the key has neither.
+export function anonymousCapsClause({
+  anonymousDailyCap,
+  anonymousMonthlyCap,
+}: {
+  anonymousDailyCap?: number | null;
+  anonymousMonthlyCap?: number | null;
+}): string {
+  let daily = anonymousDailyCap ?? null;
+  let monthly = anonymousMonthlyCap ?? null;
+  if (daily === null && monthly === null) {
+    return '';
+  }
+  let caps =
+    daily !== null && monthly !== null
+      ? `${daily} calls a day and ${monthly} a month`
+      : daily !== null
+        ? `${daily} calls a day`
+        : `${monthly} calls a month`;
+  return `, up to ${caps} all together`;
 }
 
 export interface KeyShare {
@@ -311,6 +336,7 @@ export async function addUserKey(
     ticket,
     anonymous,
     anonymousDailyCap,
+    anonymousMonthlyCap,
     ...entered
   }: {
     name: string;
@@ -318,6 +344,7 @@ export async function addUserKey(
     ticket?: string;
     anonymous?: boolean;
     anonymousDailyCap?: number;
+    anonymousMonthlyCap?: number;
   } & EnteredValue,
   fetchFn: FetchFn = fetch,
 ): Promise<UserKeyMetadata> {
@@ -340,6 +367,7 @@ export async function addUserKey(
           ...valueAttributes(entered),
           ...(anonymous ? { anonymous: true } : {}),
           ...(anonymousDailyCap !== undefined ? { anonymousDailyCap } : {}),
+          ...(anonymousMonthlyCap !== undefined ? { anonymousMonthlyCap } : {}),
         },
       },
       meta: { ticket },
@@ -376,7 +404,8 @@ export async function realmOpensToAnonymous(
 }
 
 // Sets whether people who aren't signed in may use one of the user's keys,
-// and the optional cap on their calls a day. Takes a secure session.
+// and the optional caps on their calls a day and a month. A cap left out is
+// kept, and null removes it. Takes a secure session.
 export async function setUserKeyAnonymousUse(
   realmServerUrl: string,
   token: string,
@@ -384,7 +413,14 @@ export async function setUserKeyAnonymousUse(
     keyId,
     anonymous,
     anonymousDailyCap,
-  }: { keyId: string; anonymous: boolean; anonymousDailyCap?: number },
+    anonymousMonthlyCap,
+  }: {
+    keyId: string;
+    anonymous: boolean;
+    // A cap left out is kept, and null removes it.
+    anonymousDailyCap?: number | null;
+    anonymousMonthlyCap?: number | null;
+  },
   fetchFn: FetchFn = fetch,
 ): Promise<UserKeyMetadata> {
   let json = await realmServerRequest(
@@ -400,6 +436,9 @@ export async function setUserKeyAnonymousUse(
           attributes: {
             anonymous,
             ...(anonymousDailyCap !== undefined ? { anonymousDailyCap } : {}),
+            ...(anonymousMonthlyCap !== undefined
+              ? { anonymousMonthlyCap }
+              : {}),
           },
         },
       },