@hexclave/shared 1.0.3 → 1.0.5

package/src/interface/crud/team-permissions.ts

@@ -0,0 +1,119 @@
+import { CrudTypeOf, createCrud } from "../../crud";
+import * as schemaFields from "../../schema-fields";
+import { yupMixed, yupObject } from "../../schema-fields";
+import { WebhookEvent } from "../webhooks";
+
+// =============== Team permissions =================
+
+export const teamPermissionsCrudClientReadSchema = yupObject({
+  id: schemaFields.permissionDefinitionIdSchema.defined(),
+  user_id: schemaFields.userIdSchema.defined(),
+  team_id: schemaFields.teamIdSchema.defined(),
+}).defined();
+
+export const teamPermissionsCrudServerCreateSchema = yupObject({
+}).defined();
+
+export const teamPermissionsCrudServerDeleteSchema = yupMixed();
+
+export const teamPermissionsCrud = createCrud({
+  clientReadSchema: teamPermissionsCrudClientReadSchema,
+  serverCreateSchema: teamPermissionsCrudServerCreateSchema,
+  serverDeleteSchema: teamPermissionsCrudServerDeleteSchema,
+  docs: {
+    clientList: {
+      summary: "List team permissions",
+      description: "List team permissions of the current user. `user_id=me` must be set for client requests. Note that this might contain the permissions with the same permission ID across different teams. `(team_id, user_id, permission_id)` together uniquely identify a permission.",
+      tags: ["Permissions"],
+    },
+    serverList: {
+      summary: "List team permissions of a user",
+      description: "Query and filter the permission with `team_id`, `user_id`, and `permission_id`. Note that this might contain the permissions with the same permission ID across different teams and users. `(team_id, user_id, permission_id)` together uniquely identify a permission.",
+      tags: ["Permissions"],
+    },
+    serverCreate: {
+      summary: "Grant a team permission to a user",
+      description: "Grant a team permission to a user (the team permission must be created first on the Hexclave dashboard)",
+      tags: ["Permissions"],
+    },
+    serverDelete: {
+      summary: "Revoke a team permission from a user",
+      description: "Revoke a team permission from a user",
+      tags: ["Permissions"],
+    },
+  },
+});
+export type TeamPermissionsCrud = CrudTypeOf<typeof teamPermissionsCrud>;
+
+export const teamPermissionCreatedWebhookEvent = {
+  type: "team_permission.created",
+  schema: teamPermissionsCrud.server.readSchema,
+  metadata: {
+    summary: "Team Permission Created",
+    description: "This event is triggered when a team permission is created.",
+    tags: ["Teams"],
+  },
+} satisfies WebhookEvent<typeof teamPermissionsCrud.server.readSchema>;
+
+export const teamPermissionDeletedWebhookEvent = {
+  type: "team_permission.deleted",
+  schema: teamPermissionsCrud.server.readSchema,
+  metadata: {
+    summary: "Team Permission Deleted",
+    description: "This event is triggered when a team permission is deleted.",
+    tags: ["Teams"],
+  },
+} satisfies WebhookEvent<typeof teamPermissionsCrud.server.readSchema>;
+
+// =============== Team permission definitions =================
+
+export const teamPermissionDefinitionsCrudAdminReadSchema = yupObject({
+  id: schemaFields.permissionDefinitionIdSchema.defined(),
+  description: schemaFields.teamPermissionDescriptionSchema.optional(),
+  contained_permission_ids: schemaFields.containedPermissionIdsSchema.defined(),
+}).defined();
+
+export const teamPermissionDefinitionsCrudAdminCreateSchema = yupObject({
+  id: schemaFields.customPermissionDefinitionIdSchema.defined(),
+  description: schemaFields.teamPermissionDescriptionSchema.optional(),
+  contained_permission_ids: schemaFields.containedPermissionIdsSchema.optional(),
+}).defined();
+
+export const teamPermissionDefinitionsCrudAdminUpdateSchema = yupObject({
+  id: schemaFields.customPermissionDefinitionIdSchema.optional(),
+  description: schemaFields.teamPermissionDescriptionSchema.optional(),
+  contained_permission_ids: schemaFields.containedPermissionIdsSchema.optional(),
+}).defined();
+
+export const teamPermissionDefinitionsCrudAdminDeleteSchema = yupMixed();
+
+export const teamPermissionDefinitionsCrud = createCrud({
+  adminReadSchema: teamPermissionDefinitionsCrudAdminReadSchema,
+  adminCreateSchema: teamPermissionDefinitionsCrudAdminCreateSchema,
+  adminUpdateSchema: teamPermissionDefinitionsCrudAdminUpdateSchema,
+  adminDeleteSchema: teamPermissionDefinitionsCrudAdminDeleteSchema,
+  docs: {
+    adminList: {
+      summary: "List team permission definitions",
+      description: "Query and filter the permission with team_id, user_id, and permission_id (the equivalent of listing permissions on the Hexclave dashboard)",
+      tags: ["Permissions"],
+    },
+    adminCreate: {
+      summary: "Create a new team permission definition",
+      description: "Create a new permission definition (the equivalent of creating a new permission on the Hexclave dashboard)",
+      tags: ["Permissions"],
+    },
+    adminUpdate: {
+      summary: "Update a team permission definition",
+      description: "Update a permission definition (the equivalent of updating a permission on the Hexclave dashboard)",
+      tags: ["Permissions"],
+    },
+    adminDelete: {
+      summary: "Delete a team permission definition",
+      description: "Delete a permission definition (the equivalent of deleting a permission on the Hexclave dashboard)",
+      tags: ["Permissions"],
+    },
+  },
+});
+
+export type TeamPermissionDefinitionsCrud = CrudTypeOf<typeof teamPermissionDefinitionsCrud>;

package/src/interface/crud/teams.ts

@@ -0,0 +1,142 @@
+import { CrudTypeOf, createCrud } from "../../crud";
+import * as fieldSchema from "../../schema-fields";
+import { yupObject } from "../../schema-fields";
+import { WebhookEvent } from "../webhooks";
+
+// Read
+export const teamsCrudClientReadSchema = yupObject({
+  id: fieldSchema.teamIdSchema.defined(),
+  display_name: fieldSchema.teamDisplayNameSchema.defined(),
+  profile_image_url: fieldSchema.teamProfileImageUrlSchema.nullable().defined(),
+  client_metadata: fieldSchema.teamClientMetadataSchema.optional(),
+  client_read_only_metadata: fieldSchema.teamClientReadOnlyMetadataSchema.optional(),
+}).defined();
+export const teamsCrudServerReadSchema = teamsCrudClientReadSchema.concat(yupObject({
+  created_at_millis: fieldSchema.teamCreatedAtMillisSchema.defined(),
+  server_metadata: fieldSchema.teamServerMetadataSchema.optional(),
+}).defined());
+
+// Update
+export const teamsCrudClientUpdateSchema = yupObject({
+  display_name: fieldSchema.teamDisplayNameSchema.optional(),
+  profile_image_url: fieldSchema.teamProfileImageUrlSchema.nullable().optional(),
+  client_metadata: fieldSchema.teamClientMetadataSchema.optional(),
+}).defined();
+export const teamsCrudServerUpdateSchema = teamsCrudClientUpdateSchema.concat(yupObject({
+  client_read_only_metadata: fieldSchema.teamClientReadOnlyMetadataSchema.optional(),
+  server_metadata: fieldSchema.teamServerMetadataSchema.optional(),
+}).defined());
+
+// Create
+export const teamsCrudClientCreateSchema = teamsCrudClientUpdateSchema.concat(yupObject({
+  display_name: fieldSchema.teamDisplayNameSchema.defined(),
+  creator_user_id: fieldSchema.teamCreatorUserIdSchema.optional(),
+}).defined());
+export const teamsCrudServerCreateSchema = teamsCrudServerUpdateSchema.concat(yupObject({
+  display_name: fieldSchema.teamDisplayNameSchema.defined(),
+  creator_user_id: fieldSchema.teamCreatorUserIdSchema.optional(),
+}).defined());
+
+// Delete
+export const teamsCrudClientDeleteSchema = fieldSchema.yupMixed();
+export const teamsCrudServerDeleteSchema = teamsCrudClientDeleteSchema;
+
+export const teamsCrud = createCrud({
+  // Client
+  clientReadSchema: teamsCrudClientReadSchema,
+  clientUpdateSchema: teamsCrudClientUpdateSchema,
+  clientCreateSchema: teamsCrudClientCreateSchema,
+  clientDeleteSchema: teamsCrudClientDeleteSchema,
+  // Server
+  serverReadSchema: teamsCrudServerReadSchema,
+  serverUpdateSchema: teamsCrudServerUpdateSchema,
+  serverCreateSchema: teamsCrudServerCreateSchema,
+  serverDeleteSchema: teamsCrudServerDeleteSchema,
+  docs: {
+    clientList: {
+      summary: "List teams",
+      description: "List all the teams that the current user is a member of. `user_id=me` must be passed in the query parameters.",
+      tags: ["Teams"],
+    },
+    clientCreate: {
+      summary: "Create a team",
+      description: "Create a new team and optionally add the current user as a member.",
+      tags: ["Teams"],
+    },
+    clientRead: {
+      summary: "Get a team",
+      description: "Get a team that the current user is a member of.",
+      tags: ["Teams"],
+    },
+    clientUpdate: {
+      summary: "Update a team",
+      description: "Update the team information. Only allowed if the current user is a member of the team and has the `$update_team` permission.",
+      tags: ["Teams"],
+    },
+    clientDelete: {
+      summary: "Delete a team",
+      description: "Delete a team. Only allowed if the current user is a member of the team and has the `$delete_team` permission.",
+      tags: ["Teams"],
+    },
+    serverCreate: {
+      summary: "Create a team",
+      description: "Create a new team and optionally add the current user as a member.",
+      tags: ["Teams"],
+    },
+    serverList: {
+      summary: "List teams",
+      description: "List all the teams in the project.",
+      tags: ["Teams"],
+    },
+    serverRead: {
+      summary: "Get a team",
+      description: "Get a team by ID.",
+      tags: ["Teams"],
+    },
+    serverUpdate: {
+      summary: "Update a team",
+      description: "Update the team information by ID.",
+      tags: ["Teams"],
+    },
+    serverDelete: {
+      summary: "Delete a team",
+      description: "Delete a team by ID.",
+      tags: ["Teams"],
+    },
+  },
+});
+export type TeamsCrud = CrudTypeOf<typeof teamsCrud>;
+
+export const teamCreatedWebhookEvent = {
+  type: "team.created",
+  schema: teamsCrud.server.readSchema,
+  metadata: {
+    summary: "Team Created",
+    description: "This event is triggered when a team is created.",
+    tags: ["Teams"],
+  },
+} satisfies WebhookEvent<typeof teamsCrud.server.readSchema>;
+
+export const teamUpdatedWebhookEvent = {
+  type: "team.updated",
+  schema: teamsCrud.server.readSchema,
+  metadata: {
+    summary: "Team Updated",
+    description: "This event is triggered when a team is updated.",
+    tags: ["Teams"],
+  },
+} satisfies WebhookEvent<typeof teamsCrud.server.readSchema>;
+
+const webhookTeamDeletedSchema = fieldSchema.yupObject({
+  id: fieldSchema.userIdSchema.defined(),
+}).defined();
+
+export const teamDeletedWebhookEvent = {
+  type: "team.deleted",
+  schema: webhookTeamDeletedSchema,
+  metadata: {
+    summary: "Team Deleted",
+    description: "This event is triggered when a team is deleted.",
+    tags: ["Teams"],
+  },
+} satisfies WebhookEvent<typeof webhookTeamDeletedSchema>;

package/src/interface/crud/transactions.ts

@@ -0,0 +1,131 @@
+import type { InferType } from "yup";
+import {
+  customerTypeSchema,
+  inlineProductSchema,
+  moneyAmountSchema,
+  yupArray,
+  yupBoolean,
+  yupNumber,
+  yupObject,
+  yupString,
+  yupUnion,
+} from "../../schema-fields";
+import { SUPPORTED_CURRENCIES } from "../../utils/currency-constants";
+import { typedFromEntries } from "../../utils/objects";
+import { throwErr } from "../../utils/errors";
+
+
+const USD_CURRENCY = SUPPORTED_CURRENCIES.find((currency) => currency.code === "USD") ?? throwErr("USD currency configuration missing in SUPPORTED_CURRENCIES");
+
+const chargedAmountSchema = yupObject({
+  ...typedFromEntries(SUPPORTED_CURRENCIES.map((currency) => [currency.code, moneyAmountSchema(currency).optional()])),
+}).noUnknown(true).test("at-least-one-currency", "charged_amount must include at least one currency amount", (value) => {
+  return Object.values(value).some((amount) => typeof amount === "string");
+}).defined();
+
+const netAmountSchema = yupObject({
+  USD: moneyAmountSchema(USD_CURRENCY).defined(),
+}).noUnknown(true).defined();
+
+const transactionEntryMoneyTransferSchema = yupObject({
+  type: yupString().oneOf(["money_transfer"]).defined(),
+  adjusted_transaction_id: yupString().nullable().defined(),
+  adjusted_entry_index: yupNumber().integer().min(0).nullable().defined(),
+  customer_type: customerTypeSchema.defined(),
+  customer_id: yupString().defined(),
+  charged_amount: chargedAmountSchema,
+  net_amount: netAmountSchema,
+}).defined();
+
+const transactionEntryItemQuantityChangeSchema = yupObject({
+  type: yupString().oneOf(["item_quantity_change"]).defined(),
+  adjusted_transaction_id: yupString().nullable().defined(),
+  adjusted_entry_index: yupNumber().integer().min(0).nullable().defined(),
+  customer_type: customerTypeSchema.defined(),
+  customer_id: yupString().defined(),
+  item_id: yupString().defined(),
+  quantity: yupNumber().defined(),
+}).defined();
+
+const transactionEntryProductGrantSchema = yupObject({
+  type: yupString().oneOf(["product_grant"]).defined(),
+  adjusted_transaction_id: yupString().nullable().defined(),
+  adjusted_entry_index: yupNumber().integer().min(0).nullable().defined(),
+  customer_type: customerTypeSchema.defined(),
+  customer_id: yupString().defined(),
+  product_id: yupString().nullable().defined(),
+  product: inlineProductSchema.defined(),
+  price_id: yupString().nullable().defined(),
+  quantity: yupNumber().defined(),
+  subscription_id: yupString().optional(),
+  one_time_purchase_id: yupString().optional(),
+}).test(
+  "exclusive-reference",
+  "subscription_id and one_time_purchase_id cannot both be set",
+  (value, context) => {
+    if (value.subscription_id != null && value.one_time_purchase_id != null) {
+      return context.createError({
+        message: "subscription_id and one_time_purchase_id cannot both be set",
+      });
+    }
+    return true;
+  },
+).defined();
+
+const transactionEntryProductRevocationSchema = yupObject({
+  type: yupString().oneOf(["product_revocation"]).defined(),
+  adjusted_transaction_id: yupString().defined(),
+  adjusted_entry_index: yupNumber().integer().min(0).defined(),
+  quantity: yupNumber().defined(),
+}).defined();
+
+const transactionEntryProductRevocationReversalSchema = yupObject({
+  type: yupString().oneOf(["product_revocation_reversal"]).defined(),
+  adjusted_transaction_id: yupString().defined(),
+  adjusted_entry_index: yupNumber().integer().min(0).defined(),
+  quantity: yupNumber().defined(),
+}).defined();
+
+export const transactionEntrySchema = yupUnion(
+  transactionEntryMoneyTransferSchema,
+  transactionEntryItemQuantityChangeSchema,
+  transactionEntryProductGrantSchema,
+  transactionEntryProductRevocationSchema,
+  transactionEntryProductRevocationReversalSchema,
+).defined();
+
+export type TransactionEntry = InferType<typeof transactionEntrySchema>;
+
+export const TRANSACTION_TYPES = [
+  "purchase",
+  "subscription-cancellation",
+  "subscription-renewal",
+  "manual-item-quantity-change",
+  "refund",
+  "chargeback", // todo
+  "product-change", // todo
+] as const;
+
+export type TransactionType = (typeof TRANSACTION_TYPES)[number];
+
+export const transactionSchema = yupObject({
+  id: yupString().defined(),
+  created_at_millis: yupNumber().defined(),
+  effective_at_millis: yupNumber().defined(),
+  type: yupString().oneOf(TRANSACTION_TYPES).nullable().defined(),
+  // Customer is exposed at the transaction level (not only per-entry) so
+  // consumers can attribute every row — including refund rows whose surviving
+  // entries (`product_revocation`, or none at all) carry no customer fields.
+  customer_type: customerTypeSchema.defined(),
+  customer_id: yupString().defined(),
+  entries: yupArray(transactionEntrySchema).defined(),
+  adjusted_by: yupArray(
+    yupObject({
+      transaction_id: yupString().defined(),
+      entry_index: yupNumber().integer().min(0).defined(),
+    }).defined(),
+  ).defined(),
+  test_mode: yupBoolean().defined(),
+}).defined();
+
+export type Transaction = InferType<typeof transactionSchema>;

package/src/interface/crud/users.ts

@@ -0,0 +1,185 @@
+import type { InferType } from "yup";
+import * as yup from "yup";
+import { CrudTypeOf, createCrud } from "../../crud";
+import * as fieldSchema from "../../schema-fields";
+import { WebhookEvent } from "../webhooks";
+import { teamsCrudServerReadSchema } from "./teams";
+
+const restrictedByAdminMeta = {
+  restricted_by_admin: { openapiField: { description: 'Whether the user is restricted by an administrator. Can be set manually or by sign-up rules.', exampleValue: false } },
+  restricted_by_admin_reason: { openapiField: { description: 'Public reason shown to the user explaining why they are restricted. Optional.', exampleValue: null } },
+  restricted_by_admin_private_details: { openapiField: { description: 'Private details about the restriction (e.g., which sign-up rule triggered). Only visible to server access and above.', exampleValue: null } },
+} as const;
+
+const countryCodeMeta = { openapiField: { description: 'Best-effort ISO country code captured at sign-up time from request geo headers.', exampleValue: "US" } } as const;
+
+export const riskScoreFieldSchema = fieldSchema.yupNumber().integer().min(0).max(100).defined();
+export const signUpRiskScoresSchema = fieldSchema.yupObject({
+  sign_up: fieldSchema.yupObject({
+    bot: riskScoreFieldSchema,
+    free_trial_abuse: riskScoreFieldSchema,
+  }).defined(),
+});
+export type SignUpRiskScoresCrud = InferType<typeof signUpRiskScoresSchema>["sign_up"];
+
+const oauthProviderBaseFields = {
+  id: fieldSchema.yupString().defined(),
+  account_id: fieldSchema.yupString().defined(),
+};
+const hiddenFieldMeta = { openapiField: { hidden: true } } as const;
+
+function restrictedByAdminConsistencyTest(this: yup.TestContext<any>, value: any) {
+  if (value == null) return true;
+  if (value.restricted_by_admin !== true) {
+    if (value.restricted_by_admin_reason != null) {
+      return this.createError({ message: "restricted_by_admin_reason must be null when restricted_by_admin is not true" });
+    }
+    if (value.restricted_by_admin_private_details != null) {
+      return this.createError({ message: "restricted_by_admin_private_details must be null when restricted_by_admin is not true" });
+    }
+  }
+  return true;
+}
+
+export const usersCrudServerUpdateSchema = fieldSchema.yupObject({
+  display_name: fieldSchema.userDisplayNameSchema.optional(),
+  profile_image_url: fieldSchema.profileImageUrlSchema.nullable().optional(),
+  client_metadata: fieldSchema.userClientMetadataSchema.optional(),
+  client_read_only_metadata: fieldSchema.userClientReadOnlyMetadataSchema.optional(),
+  server_metadata: fieldSchema.userServerMetadataSchema.optional(),
+  primary_email: fieldSchema.primaryEmailSchema.nullable().optional().nonEmpty(),
+  primary_email_verified: fieldSchema.primaryEmailVerifiedSchema.optional(),
+  primary_email_auth_enabled: fieldSchema.primaryEmailAuthEnabledSchema.optional(),
+  passkey_auth_enabled: fieldSchema.userOtpAuthEnabledSchema.optional(),
+  password: fieldSchema.userPasswordMutationSchema.optional(),
+  password_hash: fieldSchema.userPasswordHashMutationSchema.optional(),
+  otp_auth_enabled: fieldSchema.userOtpAuthEnabledMutationSchema.optional(),
+  totp_secret_base64: fieldSchema.userTotpSecretMutationSchema.optional(),
+  selected_team_id: fieldSchema.selectedTeamIdSchema.nullable().optional(),
+  is_anonymous: fieldSchema.yupBoolean().oneOf([false]).optional(),
+  restricted_by_admin: fieldSchema.yupBoolean().optional().meta(restrictedByAdminMeta.restricted_by_admin),
+  restricted_by_admin_reason: fieldSchema.yupString().nullable().optional().meta(restrictedByAdminMeta.restricted_by_admin_reason),
+  restricted_by_admin_private_details: fieldSchema.yupString().nullable().optional().meta(restrictedByAdminMeta.restricted_by_admin_private_details),
+  country_code: fieldSchema.countryCodeSchema.nullable().optional().meta(countryCodeMeta),
+  risk_scores: signUpRiskScoresSchema.optional(),
+}).defined().test(
+  "restricted_by_admin_consistency",
+  "When restricted_by_admin is not true, reason and private_details must be null",
+  restrictedByAdminConsistencyTest,
+);
+
+export const usersCrudServerReadSchema = fieldSchema.yupObject({
+  id: fieldSchema.userIdSchema.defined(),
+  primary_email: fieldSchema.primaryEmailSchema.nullable().defined(),
+  primary_email_verified: fieldSchema.primaryEmailVerifiedSchema.defined(),
+  primary_email_auth_enabled: fieldSchema.primaryEmailAuthEnabledSchema.defined(),
+  display_name: fieldSchema.userDisplayNameSchema.nullable().defined(),
+  selected_team: teamsCrudServerReadSchema.nullable().defined(),
+  selected_team_id: fieldSchema.selectedTeamIdSchema.nullable().defined(),
+  profile_image_url: fieldSchema.profileImageUrlSchema.nullable().defined(),
+  signed_up_at_millis: fieldSchema.signedUpAtMillisSchema.defined(),
+  has_password: fieldSchema.userHasPasswordSchema.defined(),
+  otp_auth_enabled: fieldSchema.userOtpAuthEnabledSchema.defined(),
+  passkey_auth_enabled: fieldSchema.userOtpAuthEnabledSchema.defined(),
+  client_metadata: fieldSchema.userClientMetadataSchema,
+  client_read_only_metadata: fieldSchema.userClientReadOnlyMetadataSchema,
+  server_metadata: fieldSchema.userServerMetadataSchema,
+  last_active_at_millis: fieldSchema.userLastActiveAtMillisSchema.nonNullable().defined(),
+  is_anonymous: fieldSchema.yupBoolean().defined(),
+  is_restricted: fieldSchema.yupBoolean().defined().meta({ openapiField: { description: 'Whether the user is in restricted state (has signed up but not completed onboarding requirements)', exampleValue: false } }),
+  restricted_reason: fieldSchema.restrictedReasonSchema.nullable().defined().meta({ openapiField: { description: 'The reason why the user is restricted (e.g., type: "email_not_verified", "anonymous", or "restricted_by_administrator"), null if not restricted', exampleValue: null } }),
+  restricted_by_admin: fieldSchema.yupBoolean().defined().meta(restrictedByAdminMeta.restricted_by_admin),
+  restricted_by_admin_reason: fieldSchema.yupString().nullable().defined().meta(restrictedByAdminMeta.restricted_by_admin_reason),
+  restricted_by_admin_private_details: fieldSchema.yupString().nullable().defined().meta(restrictedByAdminMeta.restricted_by_admin_private_details),
+  country_code: fieldSchema.countryCodeSchema.nullable().defined().meta(countryCodeMeta),
+  risk_scores: signUpRiskScoresSchema.defined().meta({ openapiField: { description: 'User risk scores used for sign-up risk evaluation.', exampleValue: { sign_up: { bot: 0, free_trial_abuse: 0 } } } }),
+
+  oauth_providers: fieldSchema.yupArray(fieldSchema.yupObject({
+    ...oauthProviderBaseFields,
+    email: fieldSchema.yupString().nullable(),
+  }).defined()).defined().meta(hiddenFieldMeta),
+
+  /**
+   * @deprecated
+   */
+  auth_with_email: fieldSchema.yupBoolean().defined().meta({ openapiField: { hidden: true, description: 'Whether the user can authenticate with their primary e-mail. If set to true, the user can log-in with credentials and/or magic link, if enabled in the project settings.', exampleValue: true } }),
+  /**
+   * @deprecated
+   */
+  requires_totp_mfa: fieldSchema.yupBoolean().defined().meta({ openapiField: { hidden: true, description: 'Whether the user is required to use TOTP MFA to sign in', exampleValue: false } }),
+}).defined().test("restricted_reason_iff_restricted", "restricted_reason must be present if and only if is_restricted is true", function(this: yup.TestContext<any>, value: any) {
+  if (value == null) return true;
+  return value.is_restricted === !!value.restricted_reason;
+}).test(
+  "restricted_by_admin_consistency",
+  "When restricted_by_admin is not true, reason and private_details must be null",
+  restrictedByAdminConsistencyTest,
+);
+
+export const usersCrudServerCreateSchema = usersCrudServerUpdateSchema.omit(['selected_team_id']).concat(fieldSchema.yupObject({
+  oauth_providers: fieldSchema.yupArray(fieldSchema.yupObject({
+    ...oauthProviderBaseFields,
+    email: fieldSchema.yupString().nullable().defined().default(null),
+  }).defined()).optional().meta(hiddenFieldMeta),
+  is_anonymous: fieldSchema.yupBoolean().optional(),
+}).defined());
+
+export const usersCrudServerDeleteSchema = fieldSchema.yupMixed();
+
+export const usersCrud = createCrud({
+  serverReadSchema: usersCrudServerReadSchema,
+  serverUpdateSchema: usersCrudServerUpdateSchema,
+  serverCreateSchema: usersCrudServerCreateSchema,
+  serverDeleteSchema: usersCrudServerDeleteSchema,
+  docs: {
+    serverCreate: {
+      tags: ["Users"],
+      summary: 'Create user',
+      description: 'Creates a new user. E-mail authentication is always enabled, and no password is set, meaning the only way to authenticate the newly created user is through magic link.',
+    },
+    serverRead: {
+      tags: ["Users"],
+      summary: 'Get user',
+      description: 'Gets a user by user ID.',
+    },
+    serverUpdate: {
+      tags: ["Users"],
+      summary: 'Update user',
+      description: 'Updates a user. Only the values provided will be updated.',
+    },
+    serverDelete: {
+      tags: ["Users"],
+      summary: 'Delete user',
+      description: 'Deletes a user. Use this with caution.',
+    },
+    serverList: {
+      tags: ["Users"],
+      summary: 'List users',
+      description: 'Lists all the users in the project. By default, only fully onboarded users are returned. Restricted users (those who haven\'t completed onboarding requirements like email verification) are included if `include_restricted` is set to `true`. Anonymous users are included if `include_anonymous` is set to `true` (which also includes restricted users).',
+    },
+  },
+});
+export type UsersCrud = CrudTypeOf<typeof usersCrud>;
+
+function userWebhookEvent<S extends yup.Schema>(action: string, schema: S): WebhookEvent<S> {
+  return {
+    type: `user.${action}`,
+    schema,
+    metadata: {
+      summary: `User ${action[0].toUpperCase()}${action.slice(1)}`,
+      description: `This event is triggered when a user is ${action}.`,
+      tags: ["Users"],
+    },
+  };
+}
+
+export const userCreatedWebhookEvent = userWebhookEvent("created", usersCrud.server.readSchema);
+export const userUpdatedWebhookEvent = userWebhookEvent("updated", usersCrud.server.readSchema);
+
+const webhookUserDeletedSchema = fieldSchema.yupObject({
+  id: fieldSchema.userIdSchema.defined(),
+  teams: fieldSchema.yupArray(fieldSchema.yupObject({
+    id: fieldSchema.yupString().defined(),
+  })).defined(),
+}).defined();
+export const userDeletedWebhookEvent = userWebhookEvent("deleted", webhookUserDeletedSchema);

package/src/interface/handler-urls.ts

@@ -0,0 +1,74 @@
+/**
+ * @deprecated Plain string URLs are deprecated. Use `{ type: "custom", url: "...", version: 0 }` instead.
+ */
+type DeprecatedStringUrl = string;
+
+export type HandlerPageUrls = Record<
+  | "handler"
+  | "signIn"
+  | "signUp"
+  | "signOut"
+  | "emailVerification"
+  | "passwordReset"
+  | "forgotPassword"
+  | "oauthCallback"
+  | "magicLinkCallback"
+  | "accountSettings"
+  | "teamInvitation"
+  | "cliAuthConfirm"
+  | "mfa"
+  | "error"
+  | "onboarding",
+  DeprecatedStringUrl | { type: "custom", url: string, version: number } | { type: "hosted" | "handler-component" }
+>;
+
+export type HandlerRedirectUrls = Record<
+  | "afterSignIn"
+  | "afterSignUp"
+  | "afterSignOut"
+  | "home",
+  string
+>;
+
+export type HandlerUrls = HandlerPageUrls & HandlerRedirectUrls;
+export type HandlerUrlTarget = HandlerUrls[keyof HandlerUrls];
+
+/**
+ * The default handler URL target, applied to any key not explicitly set.
+ *
+ * - `{ type: "handler-component" }` — render the page inside the local `StackHandler` component (current default, may change in the next breaking version).
+ * - `{ type: "hosted" }` — redirect to Stack's hosted auth pages.
+ */
+export type DefaultHandlerUrlTarget = { type: "hosted" | "handler-component" };
+
+/**
+ * Configuration for where each auth page/redirect lives.
+ *
+ * **`default`** — fallback target for every key not set individually:
+ *   - `{ type: "handler-component" }` — use the local `StackHandler` (current default, may change in the next breaking version).
+ *   - `{ type: "hosted" }` — use Stack's hosted auth pages.
+ *
+ * **Page keys** (`signIn`, `signUp`, `signOut`, `emailVerification`, `passwordReset`,
+ * `forgotPassword`, `oauthCallback`, `magicLinkCallback`, `accountSettings`,
+ * `teamInvitation`, `cliAuthConfirm`, `mfa`, `error`, `onboarding`, `handler`):
+ *   - A URL string (e.g. `"/my-sign-in"`) — custom path.
+ *   - `{ type: "custom", url: "...", version: 0 }` — custom URL with version tracking.
+ *   - `{ type: "hosted" }` — Stack's hosted page.
+ *   - `{ type: "handler-component" }` — local `StackHandler`.
+ *
+ * **Redirect keys** (`afterSignIn`, `afterSignUp`, `afterSignOut`, `home`):
+ *   - A URL string (e.g. `"/dashboard"`) — where to redirect after the action.
+ */
+export type HandlerUrlOptions = Partial<HandlerUrls> & { default?: DefaultHandlerUrlTarget };
+export type ResolvedHandlerUrls = {
+  [K in keyof HandlerUrls]: string;
+};
+
+export {
+  getCustomPagePrompts,
+  getLatestPageVersions,
+  type CustomPagePrompt,
+  type PageComponentKey,
+  type PageVersionEntry,
+  type PageVersions
+} from "./page-component-versions";