@oxyhq/contracts 0.33.0 → 0.34.0

package/dist/esm/accountGraph.js

@@ -36,9 +36,13 @@ export const CHILD_ACCOUNT_KINDS = [
 ];
 export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
 /**
- * Whether an operator may ACT AS an account of this kind — switch the whole app
- * into it (`POST /accounts/:id/switch`) or authorise an app to act as it
- * (an OAuth delegated subject).
+ * Whether an account of this kind may be the SUBJECT OF A DELEGATION — an
+ * application acting as it on some person's authority. `POST /internal/accounts/
+ * :id/service-switch` and the OAuth delegated subject both gate on this.
+ *
+ * It is NOT the question an account switcher asks. See
+ * {@link isOperatorSwitchTargetKind}, and the note below on why the difference
+ * is `bot`.
  *
  * Two kinds are refused, for opposite reasons:
  *
@@ -55,9 +59,43 @@ export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
  * Consumers must gate on this predicate rather than testing `kind === 'personal'`,
  * which silently admits every kind added after it was written.
  */
-export function isActAsEligibleKind(kind) {
+export function isDelegatedActAsEligibleKind(kind) {
     return kind === 'organization' || kind === 'project' || kind === 'bot';
 }
+/**
+ * Whether a PERSON may switch into an account of this kind — become it, in an
+ * account switcher, for the rest of their session.
+ *
+ * ## Why this is not the same question as {@link isDelegatedActAsEligibleKind}
+ *
+ * The two differ on exactly one kind, `bot`, and that difference is the whole
+ * reason both exist.
+ *
+ * **A bot is not something you become. It is something that operates on your
+ * behalf.** Its whole purpose is to act while nobody is present: an application
+ * holds a credential, names the human whose authority it borrows, and speaks as
+ * the bot. That is delegation, and it is what
+ * {@link isDelegatedActAsEligibleKind} admits it for.
+ *
+ * Handing a person the bot's seat instead inverts that. It puts a human inside
+ * the identity that exists to act without one, and it does so on the human's own
+ * device, next to their personal login — which is precisely what happened: a
+ * `bot` account held a live session on a person's device, offered to them by a
+ * switcher that had asked the delegation question by mistake.
+ *
+ * `channel` is refused here as well, for the reason set out above, and
+ * `personal` because assuming somebody else's login is impersonation.
+ *
+ * ## This is the narrower predicate, deliberately
+ *
+ * Everything a person may become, a service may also act as; the reverse does
+ * not hold. A caller that is unsure which question it is asking wants THIS one:
+ * being wrong here withholds an affordance, while being wrong the other way
+ * hands out a seat.
+ */
+export function isOperatorSwitchTargetKind(kind) {
+    return kind === 'organization' || kind === 'project';
+}
 /**
  * Narrow an unknown value to an {@link AccountKind}.
  *
@@ -288,7 +326,7 @@ export const accountCategoriesSchema = z
  *
  * A person has interests, not a sector — and their interests are not a
  * classification anybody else gets to read off their profile. Spelled out
- * positively, like {@link isActAsEligibleKind} and for the same reason: a `kind
+ * positively, like {@link isDelegatedActAsEligibleKind} and for the same reason: a `kind
  * !== 'personal'` test silently admits every kind invented after it was
  * written, whereas this list forces whoever adds one to decide.
  */

package/dist/esm/index.js

@@ -9,7 +9,7 @@
  * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
  * expo, no `require()` in the ESM build.
  */
-export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isActAsEligibleKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph.js';
+export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph.js';
 export { usernameSchema, isValidUsername, stripDisallowedUsernameCharacters, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, } from './username.js';
 export { 
 // Schemas