@fragno-dev/backoffice-api 0.0.0-stage → 0.0.0

package/dist/v0/shared/scope.d.ts

@@ -0,0 +1,305 @@
+import { z } from "zod";
+//#region src/v0/shared/scope.d.ts
+/** How a scope names the organization and project it belongs to. */
+type BackofficeScopeNames = {
+  organization: object;
+  project: object;
+};
+/** An organization scope, generic over how it names the organization. */
+type BackofficeOrganizationScope<TNames extends BackofficeScopeNames> = {
+  kind: "org";
+} & TNames["organization"];
+/** A user's personal scope. */
+type BackofficeUserScope = {
+  kind: "user";
+  userId: string;
+};
+/** The scopes that own everything else: every scope chain ends in an organization or a user. */
+type BackofficeRootOwner<TNames extends BackofficeScopeNames> = BackofficeOrganizationScope<TNames> | BackofficeUserScope;
+/**
+ * An installed app's own workspace, one per installation. The installation's owner owns it, and
+ * the app ID is stable, so every spelling names the app by ID.
+ */
+type BackofficeAppScope<TNames extends BackofficeScopeNames> = {
+  kind: "app";
+  owner: BackofficeRootOwner<TNames>;
+  appId: string;
+};
+/** The scopes that can own a project. Projects never own projects. */
+type BackofficeProjectOwner<TNames extends BackofficeScopeNames> = BackofficeRootOwner<TNames> | BackofficeAppScope<TNames>;
+/**
+ * Where Backoffice work runs, generic over how it names its organization and project: by ID at
+ * runtime, by slug in Backoffice URLs, or as loaded records. App and project scopes name their
+ * owner as a scope.
+ */
+type BackofficeScope<TNames extends BackofficeScopeNames> = {
+  kind: "system";
+} | BackofficeRootOwner<TNames> | BackofficeAppScope<TNames> | ({
+  kind: "project";
+  owner: BackofficeProjectOwner<TNames>;
+} & TNames["project"]);
+/** Scopes that own resources; system scope only administers them. */
+type BackofficeRoutable<TScope extends {
+  kind: string;
+}> = Exclude<TScope, {
+  kind: "system";
+}>;
+type BackofficeScopeIdNames = {
+  organization: {
+    orgId: string;
+  };
+  project: {
+    projectId: string;
+  };
+};
+/** Where Backoffice work runs, naming organizations and projects by ID. */
+type BackofficeContextScope = BackofficeScope<BackofficeScopeIdNames>;
+type BackofficeRoutableScope = BackofficeRoutable<BackofficeContextScope>;
+/**
+ * Public routes and CLI arguments name organizations by slug, never by internal ID. Projects keep
+ * their ID, because public URLs are registered with external services and must survive renames.
+ */
+type BackofficeScopePublicNames = {
+  organization: {
+    orgSlug: string;
+  };
+  project: {
+    projectId: string;
+  };
+};
+type BackofficePublicScope = BackofficeScope<BackofficeScopePublicNames>;
+declare const backofficeOrganizationScopeSchema: z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"org">;
+  orgId: z.ZodString;
+}, z.core.$strict>>;
+declare const backofficeUserScopeSchema: z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"user">;
+  userId: z.ZodString;
+}, z.core.$strict>>;
+declare const backofficeRootOwnerSchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"org">;
+  orgId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"user">;
+  userId: z.ZodString;
+}, z.core.$strict>>], "kind">>;
+declare const backofficeAppScopeSchema: z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"app">;
+  owner: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+  }, z.core.$strict>>], "kind">>;
+  appId: z.ZodString;
+}, z.core.$strict>>;
+declare const backofficeProjectScopeSchema: z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"project">;
+  owner: z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"app">;
+    owner: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+      kind: z.ZodLiteral<"org">;
+      orgId: z.ZodString;
+    }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+      kind: z.ZodLiteral<"user">;
+      userId: z.ZodString;
+    }, z.core.$strict>>], "kind">>;
+    appId: z.ZodString;
+  }, z.core.$strict>>], "kind">;
+  projectId: z.ZodString;
+}, z.core.$strict>>;
+declare const backofficeRoutableScopeSchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"org">;
+  orgId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"user">;
+  userId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"app">;
+  owner: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+  }, z.core.$strict>>], "kind">>;
+  appId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"project">;
+  owner: z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"app">;
+    owner: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+      kind: z.ZodLiteral<"org">;
+      orgId: z.ZodString;
+    }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+      kind: z.ZodLiteral<"user">;
+      userId: z.ZodString;
+    }, z.core.$strict>>], "kind">>;
+    appId: z.ZodString;
+  }, z.core.$strict>>], "kind">;
+  projectId: z.ZodString;
+}, z.core.$strict>>], "kind">>;
+declare const backofficeContextScopeSchema: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"system">;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"org">;
+  orgId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"user">;
+  userId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"app">;
+  owner: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+  }, z.core.$strict>>], "kind">>;
+  appId: z.ZodString;
+}, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+  kind: z.ZodLiteral<"project">;
+  owner: z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"org">;
+    orgId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    userId: z.ZodString;
+  }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+    kind: z.ZodLiteral<"app">;
+    owner: z.ZodLazy<z.ZodDiscriminatedUnion<[z.ZodLazy<z.ZodObject<{
+      kind: z.ZodLiteral<"org">;
+      orgId: z.ZodString;
+    }, z.core.$strict>>, z.ZodLazy<z.ZodObject<{
+      kind: z.ZodLiteral<"user">;
+      userId: z.ZodString;
+    }, z.core.$strict>>], "kind">>;
+    appId: z.ZodString;
+  }, z.core.$strict>>], "kind">;
+  projectId: z.ZodString;
+}, z.core.$strict>>], "kind">>;
+declare function isBackofficeRoutableScope(scope: BackofficeContextScope): scope is BackofficeRoutableScope;
+type ProjectNamesOf<TScope> = Omit<Extract<TScope, {
+  kind: "project";
+}>, "kind" | "owner">;
+/** The root owners among a scope type's kinds, found by following each owner chain. */
+type BackofficeRootOwnerOf<TScope> = TScope extends {
+  kind: "org";
+} | {
+  kind: "user";
+} ? TScope : TScope extends {
+  owner: infer TOwner;
+} ? BackofficeRootOwnerOf<TOwner> : never;
+/** The organization scope a scope type's chains can end in. */
+type BackofficeOrganizationScopeOf<TScope> = Extract<BackofficeRootOwnerOf<TScope>, {
+  kind: "org";
+}>;
+type OrganizationNamesOf<TScope> = Omit<BackofficeOrganizationScopeOf<TScope>, "kind">;
+/** `null` when a scope type includes the system scope, which no root owner owns. */
+type NullIfSystem<TScope> = [Extract<TScope, {
+  kind: "system";
+}>] extends [never] ? never : null;
+/** `null` when a scope type includes scopes that belong to no organization. */
+type NullUnlessOrganizationOwned<TScope> = [Extract<TScope, {
+  kind: "system";
+}> | Extract<BackofficeRootOwnerOf<TScope>, {
+  kind: "user";
+}>] extends [never] ? never : null;
+/**
+ * The organization or user at the end of a scope's owner chain, who answers for everything in it.
+ * The system scope has none, so the result is only nullable when the scope type includes it.
+ */
+declare function backofficeScopeRootOwner<TScope extends BackofficeScope<BackofficeScopeNames>>(scope: TScope): BackofficeRootOwnerOf<TScope> | NullIfSystem<TScope>;
+/**
+ * The organization a scope belongs to: its root owner, when that is an organization. The result is
+ * only nullable when the scope type includes scopes that a user or nobody owns.
+ */
+declare function backofficeScopeOrganization<TScope extends BackofficeScope<BackofficeScopeNames>>(scope: TScope): BackofficeOrganizationScopeOf<TScope> | NullUnlessOrganizationOwned<TScope>;
+/**
+ * The scope whose projects sit beside a workspace: the workspace itself, or a project's owner.
+ * The system scope owns no projects.
+ */
+declare function backofficeScopeProjectOwner<TNames extends BackofficeScopeNames>(scope: BackofficeScope<TNames>): BackofficeProjectOwner<TNames> | null;
+/**
+ * The organization whose own workspace a scope is: the organization, or one of its projects. Unlike
+ * `backofficeScopeOrganization`, an installed app's workspace is not its organization's.
+ */
+declare function backofficeWorkspaceOrganization<TNames extends BackofficeScopeNames>(scope: BackofficeScope<TNames>): BackofficeOrganizationScope<TNames> | null;
+/** Renames the records a scope refers to, e.g. from route slugs to runtime IDs; kinds are kept. */
+declare function mapBackofficeScopeNames<TScope extends BackofficeScope<BackofficeScopeNames>, TOrganization extends object, TProject extends object>(scope: TScope, map: {
+  organization(names: OrganizationNamesOf<TScope>): TOrganization;
+  project(names: ProjectNamesOf<TScope>): TProject;
+}): Extract<BackofficeScope<{
+  organization: TOrganization;
+  project: TProject;
+}>, {
+  kind: TScope["kind"];
+}>;
+declare function backofficeContextScopesEqual(left: BackofficeContextScope, right: BackofficeContextScope): boolean;
+/**
+ * A scope restriction is an upper bound: a project's owner contains the project. Containment does
+ * not chain, so an organization contains neither its apps' workspaces nor their projects.
+ */
+declare function backofficeScopeContains(restriction: BackofficeContextScope, target: BackofficeContextScope): boolean;
+/** A scope could not be read from untrusted text, such as a URL. */
+declare class BackofficeScopeParseError extends Error {
+  readonly code = "INVALID_BACKOFFICE_SCOPE";
+  constructor(message: string);
+}
+/** Matches by code too, because errors lose their class across module copies and RPC. */
+declare function isBackofficeScopeParseError(error: unknown): error is BackofficeScopeParseError;
+/** How one of a scope's names is written in text, and what a parse error calls it. */
+type BackofficeNameCodec<TName extends object> = {
+  label: string;
+  format(name: TName): string;
+  parse(value: string): TName;
+};
+type BackofficeScopeCodec<TNames extends BackofficeScopeNames> = {
+  organization: BackofficeNameCodec<TNames["organization"]>;
+  project: BackofficeNameCodec<TNames["project"]>;
+};
+declare const backofficeOrganizationSlugCodec: BackofficeNameCodec<{
+  orgSlug: string;
+}>;
+declare const backofficeScopeIdCodec: BackofficeScopeCodec<BackofficeScopeIdNames>;
+declare const backofficePublicScopeCodec: BackofficeScopeCodec<BackofficeScopePublicNames>;
+/**
+ * Names a scope in one URL path segment, e.g. `project:org:<org>:<projectId>`: app and project
+ * scopes embed their owner's segment. Components are URI-encoded, so `:` only ever separates them.
+ */
+declare function formatBackofficeScopeSegment<TNames extends BackofficeScopeNames>(scope: BackofficeScope<TNames>, codec: BackofficeScopeCodec<TNames>): string;
+/** Reads a segment written by `formatBackofficeScopeSegment`; anything else is a parse error. */
+declare function parseBackofficeScopeSegment<TNames extends BackofficeScopeNames>(segment: string, codec: BackofficeScopeCodec<TNames>): BackofficeScope<TNames>;
+/**
+ * Escapes scope text for a URL path segment that a router decodes once before it is parsed. Paths
+ * allow a literal `:`, so the separator stays readable; a `:` inside a component was already
+ * escaped when the segment was formatted.
+ */
+declare function encodeBackofficeScopeForPath(text: string): string;
+/** Names a scope in two URL path segments, `<kind>/<id>`, e.g. `project/org:acme:website`. */
+declare function formatBackofficeScopeRoutePath<TNames extends BackofficeScopeNames>(scope: BackofficeScope<TNames>, codec: BackofficeScopeCodec<TNames>): string;
+/** Reads the decoded `<kind>/<id>` route parameters written by `formatBackofficeScopeRoutePath`. */
+declare function parseBackofficeScopeRouteParams<TNames extends BackofficeScopeNames>(params: {
+  scopeKind: string;
+  scopeId: string;
+}, codec: BackofficeScopeCodec<TNames>): BackofficeScope<TNames>;
+/** Names an ID-backed scope in one URL path segment, as the Backoffice API addresses scopes. */
+declare function backofficeScopePathSegment(scope: BackofficeContextScope): string;
+/** Reads a segment written by `backofficeScopePathSegment`; anything else is a parse error. */
+declare function parseBackofficeScopePathSegment(segment: string): BackofficeContextScope;
+//#endregion
+export { BackofficeAppScope, BackofficeContextScope, BackofficeNameCodec, BackofficeOrganizationScope, BackofficeOrganizationScopeOf, BackofficeProjectOwner, BackofficePublicScope, BackofficeRootOwner, BackofficeRootOwnerOf, BackofficeRoutable, BackofficeRoutableScope, BackofficeScope, BackofficeScopeCodec, BackofficeScopeIdNames, BackofficeScopeNames, BackofficeScopeParseError, BackofficeScopePublicNames, BackofficeUserScope, backofficeAppScopeSchema, backofficeContextScopeSchema, backofficeContextScopesEqual, backofficeOrganizationScopeSchema, backofficeOrganizationSlugCodec, backofficeProjectScopeSchema, backofficePublicScopeCodec, backofficeRootOwnerSchema, backofficeRoutableScopeSchema, backofficeScopeContains, backofficeScopeIdCodec, backofficeScopeOrganization, backofficeScopePathSegment, backofficeScopeProjectOwner, backofficeScopeRootOwner, backofficeUserScopeSchema, backofficeWorkspaceOrganization, encodeBackofficeScopeForPath, formatBackofficeScopeRoutePath, formatBackofficeScopeSegment, isBackofficeRoutableScope, isBackofficeScopeParseError, mapBackofficeScopeNames, parseBackofficeScopePathSegment, parseBackofficeScopeRouteParams, parseBackofficeScopeSegment };
+//# sourceMappingURL=scope.d.ts.map

package/dist/v0/shared/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","names":[],"sources":["../../../src/v0/shared/scope.ts"],"mappings":"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"}

package/dist/v0/shared/scope.js

@@ -0,0 +1,279 @@
+import { z } from "zod";
+//#region src/v0/shared/scope.ts
+const backofficeSystemScopeSchema = z.lazy(() => z.strictObject({ kind: z.literal("system") }));
+const backofficeOrganizationScopeSchema = z.lazy(() => z.strictObject({
+	kind: z.literal("org"),
+	orgId: z.string().trim().min(1)
+}));
+const backofficeUserScopeSchema = z.lazy(() => z.strictObject({
+	kind: z.literal("user"),
+	userId: z.string().trim().min(1)
+}));
+const backofficeRootOwnerSchema = z.lazy(() => z.discriminatedUnion("kind", [backofficeOrganizationScopeSchema, backofficeUserScopeSchema]));
+const backofficeAppScopeSchema = z.lazy(() => z.strictObject({
+	kind: z.literal("app"),
+	owner: backofficeRootOwnerSchema,
+	appId: z.string().trim().min(1)
+}));
+const backofficeProjectScopeSchema = z.lazy(() => z.strictObject({
+	kind: z.literal("project"),
+	owner: z.discriminatedUnion("kind", [
+		backofficeOrganizationScopeSchema,
+		backofficeUserScopeSchema,
+		backofficeAppScopeSchema
+	]),
+	projectId: z.string().trim().min(1)
+}));
+const backofficeRoutableScopeSchema = z.lazy(() => z.discriminatedUnion("kind", [
+	backofficeOrganizationScopeSchema,
+	backofficeUserScopeSchema,
+	backofficeAppScopeSchema,
+	backofficeProjectScopeSchema
+]));
+const backofficeContextScopeSchema = z.lazy(() => z.discriminatedUnion("kind", [
+	backofficeSystemScopeSchema,
+	backofficeOrganizationScopeSchema,
+	backofficeUserScopeSchema,
+	backofficeAppScopeSchema,
+	backofficeProjectScopeSchema
+]));
+function isBackofficeRoutableScope(scope) {
+	return scope.kind !== "system";
+}
+/**
+* The organization or user at the end of a scope's owner chain, who answers for everything in it.
+* The system scope has none, so the result is only nullable when the scope type includes it.
+*/
+function backofficeScopeRootOwner(scope) {
+	const named = scope;
+	switch (named.kind) {
+		case "org":
+		case "user": return named;
+		case "app":
+		case "project": return backofficeScopeRootOwner(named.owner);
+		case "system": return null;
+		default: throw new Error("Unsupported Backoffice scope kind.", { cause: named });
+	}
+}
+/**
+* The organization a scope belongs to: its root owner, when that is an organization. The result is
+* only nullable when the scope type includes scopes that a user or nobody owns.
+*/
+function backofficeScopeOrganization(scope) {
+	const owner = backofficeScopeRootOwner(scope);
+	return owner?.kind === "org" ? owner : null;
+}
+/**
+* The scope whose projects sit beside a workspace: the workspace itself, or a project's owner.
+* The system scope owns no projects.
+*/
+function backofficeScopeProjectOwner(scope) {
+	switch (scope.kind) {
+		case "system": return null;
+		case "project": return scope.owner;
+		case "org":
+		case "user":
+		case "app": return scope;
+		default: throw new Error("Unsupported Backoffice scope kind.", { cause: scope });
+	}
+}
+/**
+* The organization whose own workspace a scope is: the organization, or one of its projects. Unlike
+* `backofficeScopeOrganization`, an installed app's workspace is not its organization's.
+*/
+function backofficeWorkspaceOrganization(scope) {
+	const owner = backofficeScopeProjectOwner(scope);
+	return owner?.kind === "org" ? owner : null;
+}
+/** Renames the records a scope refers to, e.g. from route slugs to runtime IDs; kinds are kept. */
+function mapBackofficeScopeNames(scope, map) {
+	return renameScope(scope);
+	function renameScope(named) {
+		switch (named.kind) {
+			case "system": return { kind: "system" };
+			case "org": return {
+				kind: "org",
+				...map.organization(named)
+			};
+			case "user": return {
+				kind: "user",
+				userId: named.userId
+			};
+			case "app": return {
+				kind: "app",
+				owner: renameScope(named.owner),
+				appId: named.appId
+			};
+			case "project": return {
+				kind: "project",
+				...map.project(named),
+				owner: renameScope(named.owner)
+			};
+			default: throw new Error("Unsupported Backoffice scope kind.", { cause: named });
+		}
+	}
+}
+function backofficeContextScopesEqual(left, right) {
+	return backofficeScopePathSegment(left) === backofficeScopePathSegment(right);
+}
+/**
+* A scope restriction is an upper bound: a project's owner contains the project. Containment does
+* not chain, so an organization contains neither its apps' workspaces nor their projects.
+*/
+function backofficeScopeContains(restriction, target) {
+	return backofficeContextScopesEqual(restriction, target) || target.kind === "project" && backofficeContextScopesEqual(restriction, target.owner);
+}
+const INVALID_BACKOFFICE_SCOPE = "INVALID_BACKOFFICE_SCOPE";
+/** A scope could not be read from untrusted text, such as a URL. */
+var BackofficeScopeParseError = class extends Error {
+	code = INVALID_BACKOFFICE_SCOPE;
+	constructor(message) {
+		super(message);
+		this.name = "BackofficeScopeParseError";
+	}
+};
+/** Matches by code too, because errors lose their class across module copies and RPC. */
+function isBackofficeScopeParseError(error) {
+	return error instanceof BackofficeScopeParseError || typeof error === "object" && error !== null && "code" in error && error.code === INVALID_BACKOFFICE_SCOPE;
+}
+const organizationIdCodec = {
+	label: "org id",
+	format: (name) => name.orgId,
+	parse: (orgId) => ({ orgId })
+};
+const projectIdCodec = {
+	label: "project id",
+	format: (name) => name.projectId,
+	parse: (projectId) => ({ projectId })
+};
+const backofficeOrganizationSlugCodec = {
+	label: "organization slug",
+	format: (name) => name.orgSlug,
+	parse: (orgSlug) => ({ orgSlug })
+};
+const backofficeScopeIdCodec = {
+	organization: organizationIdCodec,
+	project: projectIdCodec
+};
+const backofficePublicScopeCodec = {
+	organization: backofficeOrganizationSlugCodec,
+	project: projectIdCodec
+};
+/**
+* Names a scope in one URL path segment, e.g. `project:org:<org>:<projectId>`: app and project
+* scopes embed their owner's segment. Components are URI-encoded, so `:` only ever separates them.
+*/
+function formatBackofficeScopeSegment(scope, codec) {
+	switch (scope.kind) {
+		case "system": return "system";
+		case "org": return `org:${encodeURIComponent(codec.organization.format(scope))}`;
+		case "user": return `user:${encodeURIComponent(scope.userId)}`;
+		case "app": return `app:${formatBackofficeScopeSegment(scope.owner, codec)}:${encodeURIComponent(scope.appId)}`;
+		case "project": return `project:${formatBackofficeScopeSegment(scope.owner, codec)}:${encodeURIComponent(codec.project.format(scope))}`;
+		default: throw new Error("Unsupported Backoffice scope kind.", { cause: scope });
+	}
+}
+/** Reads a segment written by `formatBackofficeScopeSegment`; anything else is a parse error. */
+function parseBackofficeScopeSegment(segment, codec) {
+	const components = segment.split(":");
+	let next = 0;
+	const scope = readScope();
+	if (next !== components.length) throw new BackofficeScopeParseError(`${scopeLabel(scope.kind)} scope has unexpected components after it.`);
+	return scope;
+	function readScope() {
+		const kind = components[next++];
+		switch (kind) {
+			case "system": return { kind: "system" };
+			case "org": return {
+				kind: "org",
+				...codec.organization.parse(readComponent(codec.organization.label))
+			};
+			case "user": return {
+				kind: "user",
+				userId: readComponent("user id")
+			};
+			case "app": {
+				const owner = readOwner("App");
+				if (owner.kind !== "org" && owner.kind !== "user") throw new BackofficeScopeParseError(`${scopeLabel(owner.kind)} scope cannot own an app.`);
+				return {
+					kind: "app",
+					owner,
+					appId: readComponent("app id")
+				};
+			}
+			case "project": {
+				const owner = readOwner("Project");
+				if (owner.kind === "system" || owner.kind === "project") throw new BackofficeScopeParseError(`${scopeLabel(owner.kind)} scope cannot own a project.`);
+				return {
+					kind: "project",
+					owner,
+					...codec.project.parse(readComponent(codec.project.label))
+				};
+			}
+			default: throw new BackofficeScopeParseError(`Unknown scope kind '${kind ?? ""}'.`);
+		}
+	}
+	function readOwner(ownedLabel) {
+		if (next === components.length) throw new BackofficeScopeParseError(`${ownedLabel} scope requires an owner scope.`);
+		return readScope();
+	}
+	function readComponent(label) {
+		const value = components[next++];
+		if (value === void 0) throw new BackofficeScopeParseError(`Missing ${label}.`);
+		return decodeSegmentComponent(value, label);
+	}
+}
+function decodeSegmentComponent(value, label) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(value);
+	} catch {
+		throw new BackofficeScopeParseError(`Invalid ${label} encoding.`);
+	}
+	if (!decoded) throw new BackofficeScopeParseError(`Missing ${label}.`);
+	return decoded;
+}
+function scopeLabel(kind) {
+	switch (kind) {
+		case "system": return "System";
+		case "org": return "Org";
+		case "user": return "User";
+		case "app": return "App";
+		case "project": return "Project";
+		default: throw new Error("Unsupported Backoffice scope kind.", { cause: kind });
+	}
+}
+/**
+* Escapes scope text for a URL path segment that a router decodes once before it is parsed. Paths
+* allow a literal `:`, so the separator stays readable; a `:` inside a component was already
+* escaped when the segment was formatted.
+*/
+function encodeBackofficeScopeForPath(text) {
+	return encodeURIComponent(text).replaceAll("%3A", ":");
+}
+/** Names a scope in two URL path segments, `<kind>/<id>`, e.g. `project/org:acme:website`. */
+function formatBackofficeScopeRoutePath(scope, codec) {
+	if (scope.kind === "system") return "system/system";
+	const components = formatBackofficeScopeSegment(scope, codec).slice(scope.kind.length + 1);
+	return `${scope.kind}/${encodeBackofficeScopeForPath(components)}`;
+}
+/** Reads the decoded `<kind>/<id>` route parameters written by `formatBackofficeScopeRoutePath`. */
+function parseBackofficeScopeRouteParams(params, codec) {
+	if (params.scopeKind === "system") {
+		if (params.scopeId !== "system") throw new BackofficeScopeParseError("System scope requires the system id.");
+		return { kind: "system" };
+	}
+	return parseBackofficeScopeSegment(`${params.scopeKind}:${params.scopeId}`, codec);
+}
+/** Names an ID-backed scope in one URL path segment, as the Backoffice API addresses scopes. */
+function backofficeScopePathSegment(scope) {
+	return formatBackofficeScopeSegment(scope, backofficeScopeIdCodec);
+}
+/** Reads a segment written by `backofficeScopePathSegment`; anything else is a parse error. */
+function parseBackofficeScopePathSegment(segment) {
+	return parseBackofficeScopeSegment(segment, backofficeScopeIdCodec);
+}
+//#endregion
+export { BackofficeScopeParseError, backofficeAppScopeSchema, backofficeContextScopeSchema, backofficeContextScopesEqual, backofficeOrganizationScopeSchema, backofficeOrganizationSlugCodec, backofficeProjectScopeSchema, backofficePublicScopeCodec, backofficeRootOwnerSchema, backofficeRoutableScopeSchema, backofficeScopeContains, backofficeScopeIdCodec, backofficeScopeOrganization, backofficeScopePathSegment, backofficeScopeProjectOwner, backofficeScopeRootOwner, backofficeUserScopeSchema, backofficeWorkspaceOrganization, encodeBackofficeScopeForPath, formatBackofficeScopeRoutePath, formatBackofficeScopeSegment, isBackofficeRoutableScope, isBackofficeScopeParseError, mapBackofficeScopeNames, parseBackofficeScopePathSegment, parseBackofficeScopeRouteParams, parseBackofficeScopeSegment };
+
+//# sourceMappingURL=scope.js.map

package/dist/v0/shared/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","names":[],"sources":["../../../src/v0/shared/scope.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/** How a scope names the organization and project it belongs to. */\nexport type BackofficeScopeNames = { organization: object; project: object };\n\n/** An organization scope, generic over how it names the organization. */\nexport type BackofficeOrganizationScope<TNames extends BackofficeScopeNames> = {\n  kind: \"org\";\n} & TNames[\"organization\"];\n\n/** A user's personal scope. */\nexport type BackofficeUserScope = { kind: \"user\"; userId: string };\n\n/** The scopes that own everything else: every scope chain ends in an organization or a user. */\nexport type BackofficeRootOwner<TNames extends BackofficeScopeNames> =\n  | BackofficeOrganizationScope<TNames>\n  | BackofficeUserScope;\n\n/**\n * An installed app's own workspace, one per installation. The installation's owner owns it, and\n * the app ID is stable, so every spelling names the app by ID.\n */\nexport type BackofficeAppScope<TNames extends BackofficeScopeNames> = {\n  kind: \"app\";\n  owner: BackofficeRootOwner<TNames>;\n  appId: string;\n};\n\n/** The scopes that can own a project. Projects never own projects. */\nexport type BackofficeProjectOwner<TNames extends BackofficeScopeNames> =\n  | BackofficeRootOwner<TNames>\n  | BackofficeAppScope<TNames>;\n\n/**\n * Where Backoffice work runs, generic over how it names its organization and project: by ID at\n * runtime, by slug in Backoffice URLs, or as loaded records. App and project scopes name their\n * owner as a scope.\n */\nexport type BackofficeScope<TNames extends BackofficeScopeNames> =\n  | { kind: \"system\" }\n  | BackofficeRootOwner<TNames>\n  | BackofficeAppScope<TNames>\n  | ({ kind: \"project\"; owner: BackofficeProjectOwner<TNames> } & TNames[\"project\"]);\n\n/** Scopes that own resources; system scope only administers them. */\nexport type BackofficeRoutable<TScope extends { kind: string }> = Exclude<\n  TScope,\n  { kind: \"system\" }\n>;\n\nexport type BackofficeScopeIdNames = {\n  organization: { orgId: string };\n  project: { projectId: string };\n};\n\n/** Where Backoffice work runs, naming organizations and projects by ID. */\nexport type BackofficeContextScope = BackofficeScope<BackofficeScopeIdNames>;\n\nexport type BackofficeRoutableScope = BackofficeRoutable<BackofficeContextScope>;\n\n/**\n * Public routes and CLI arguments name organizations by slug, never by internal ID. Projects keep\n * their ID, because public URLs are registered with external services and must survive renames.\n */\nexport type BackofficeScopePublicNames = {\n  organization: { orgSlug: string };\n  project: { projectId: string };\n};\n\nexport type BackofficePublicScope = BackofficeScope<BackofficeScopePublicNames>;\n\nconst backofficeSystemScopeSchema = z.lazy(() => z.strictObject({ kind: z.literal(\"system\") }));\nexport const backofficeOrganizationScopeSchema = z.lazy(() =>\n  z.strictObject({\n    kind: z.literal(\"org\"),\n    orgId: z.string().trim().min(1),\n  }),\n);\nexport const backofficeUserScopeSchema = z.lazy(() =>\n  z.strictObject({\n    kind: z.literal(\"user\"),\n    userId: z.string().trim().min(1),\n  }),\n);\nexport const backofficeRootOwnerSchema = z.lazy(() =>\n  z.discriminatedUnion(\"kind\", [backofficeOrganizationScopeSchema, backofficeUserScopeSchema]),\n);\nexport const backofficeAppScopeSchema = z.lazy(() =>\n  z.strictObject({\n    kind: z.literal(\"app\"),\n    owner: backofficeRootOwnerSchema,\n    appId: z.string().trim().min(1),\n  }),\n);\nexport const backofficeProjectScopeSchema = z.lazy(() =>\n  z.strictObject({\n    kind: z.literal(\"project\"),\n    owner: z.discriminatedUnion(\"kind\", [\n      backofficeOrganizationScopeSchema,\n      backofficeUserScopeSchema,\n      backofficeAppScopeSchema,\n    ]),\n    projectId: z.string().trim().min(1),\n  }),\n);\n\nexport const backofficeRoutableScopeSchema = z.lazy(() =>\n  z.discriminatedUnion(\"kind\", [\n    backofficeOrganizationScopeSchema,\n    backofficeUserScopeSchema,\n    backofficeAppScopeSchema,\n    backofficeProjectScopeSchema,\n  ]),\n) satisfies z.ZodType<BackofficeRoutableScope>;\n\nexport const backofficeContextScopeSchema = z.lazy(() =>\n  z.discriminatedUnion(\"kind\", [\n    backofficeSystemScopeSchema,\n    backofficeOrganizationScopeSchema,\n    backofficeUserScopeSchema,\n    backofficeAppScopeSchema,\n    backofficeProjectScopeSchema,\n  ]),\n) satisfies z.ZodType<BackofficeContextScope>;\n\nexport function isBackofficeRoutableScope(\n  scope: BackofficeContextScope,\n): scope is BackofficeRoutableScope {\n  return scope.kind !== \"system\";\n}\n\ntype ProjectNamesOf<TScope> = Omit<Extract<TScope, { kind: \"project\" }>, \"kind\" | \"owner\">;\n\n/** The root owners among a scope type's kinds, found by following each owner chain. */\nexport type BackofficeRootOwnerOf<TScope> = TScope extends { kind: \"org\" } | { kind: \"user\" }\n  ? TScope\n  : TScope extends { owner: infer TOwner }\n    ? BackofficeRootOwnerOf<TOwner>\n    : never;\n\n/** The organization scope a scope type's chains can end in. */\nexport type BackofficeOrganizationScopeOf<TScope> = Extract<\n  BackofficeRootOwnerOf<TScope>,\n  { kind: \"org\" }\n>;\n\ntype OrganizationNamesOf<TScope> = Omit<BackofficeOrganizationScopeOf<TScope>, \"kind\">;\n\n/** `null` when a scope type includes the system scope, which no root owner owns. */\ntype NullIfSystem<TScope> = [Extract<TScope, { kind: \"system\" }>] extends [never] ? never : null;\n\n/** `null` when a scope type includes scopes that belong to no organization. */\ntype NullUnlessOrganizationOwned<TScope> = [\n  Extract<TScope, { kind: \"system\" }> | Extract<BackofficeRootOwnerOf<TScope>, { kind: \"user\" }>,\n] extends [never]\n  ? never\n  : null;\n\n/**\n * The organization or user at the end of a scope's owner chain, who answers for everything in it.\n * The system scope has none, so the result is only nullable when the scope type includes it.\n */\nexport function backofficeScopeRootOwner<TScope extends BackofficeScope<BackofficeScopeNames>>(\n  scope: TScope,\n): BackofficeRootOwnerOf<TScope> | NullIfSystem<TScope> {\n  const named: BackofficeScope<BackofficeScopeNames> = scope;\n  switch (named.kind) {\n    case \"org\":\n    case \"user\":\n      return named as BackofficeRootOwnerOf<TScope>;\n    case \"app\":\n    case \"project\":\n      return backofficeScopeRootOwner(named.owner) as BackofficeRootOwnerOf<TScope>;\n    case \"system\":\n      return null as NullIfSystem<TScope>;\n    default:\n      throw new Error(\"Unsupported Backoffice scope kind.\", { cause: named satisfies never });\n  }\n}\n\n/**\n * The organization a scope belongs to: its root owner, when that is an organization. The result is\n * only nullable when the scope type includes scopes that a user or nobody owns.\n */\nexport function backofficeScopeOrganization<TScope extends BackofficeScope<BackofficeScopeNames>>(\n  scope: TScope,\n): BackofficeOrganizationScopeOf<TScope> | NullUnlessOrganizationOwned<TScope> {\n  const owner: BackofficeRootOwner<BackofficeScopeNames> | null = backofficeScopeRootOwner(scope);\n  return (owner?.kind === \"org\" ? owner : null) as\n    | BackofficeOrganizationScopeOf<TScope>\n    | NullUnlessOrganizationOwned<TScope>;\n}\n\n/**\n * The scope whose projects sit beside a workspace: the workspace itself, or a project's owner.\n * The system scope owns no projects.\n */\nexport function backofficeScopeProjectOwner<TNames extends BackofficeScopeNames>(\n  scope: BackofficeScope<TNames>,\n): BackofficeProjectOwner<TNames> | null {\n  switch (scope.kind) {\n    case \"system\":\n      return null;\n    case \"project\":\n      return scope.owner;\n    case \"org\":\n    case \"user\":\n    case \"app\":\n      return scope;\n    default:\n      throw new Error(\"Unsupported Backoffice scope kind.\", { cause: scope satisfies never });\n  }\n}\n\n/**\n * The organization whose own workspace a scope is: the organization, or one of its projects. Unlike\n * `backofficeScopeOrganization`, an installed app's workspace is not its organization's.\n */\nexport function backofficeWorkspaceOrganization<TNames extends BackofficeScopeNames>(\n  scope: BackofficeScope<TNames>,\n): BackofficeOrganizationScope<TNames> | null {\n  const owner = backofficeScopeProjectOwner(scope);\n  return owner?.kind === \"org\" ? owner : null;\n}\n\n/** Renames the records a scope refers to, e.g. from route slugs to runtime IDs; kinds are kept. */\nexport function mapBackofficeScopeNames<\n  TScope extends BackofficeScope<BackofficeScopeNames>,\n  TOrganization extends object,\n  TProject extends object,\n>(\n  scope: TScope,\n  map: {\n    organization(names: OrganizationNamesOf<TScope>): TOrganization;\n    project(names: ProjectNamesOf<TScope>): TProject;\n  },\n): Extract<\n  BackofficeScope<{ organization: TOrganization; project: TProject }>,\n  { kind: TScope[\"kind\"] }\n> {\n  return renameScope(scope) as Extract<\n    BackofficeScope<{ organization: TOrganization; project: TProject }>,\n    { kind: TScope[\"kind\"] }\n  >;\n\n  // Narrowing a generic scope by kind does not narrow `TScope`, so each kind's names are cast to\n  // the callback types. A project's owner is renamed as a scope of its own.\n  function renameScope(\n    named: BackofficeScope<BackofficeScopeNames>,\n  ): BackofficeScope<{ organization: TOrganization; project: TProject }> {\n    switch (named.kind) {\n      case \"system\":\n        return { kind: \"system\" };\n      case \"org\":\n        return { kind: \"org\", ...map.organization(named as OrganizationNamesOf<TScope>) };\n      case \"user\":\n        return { kind: \"user\", userId: named.userId };\n      case \"app\":\n        return {\n          kind: \"app\",\n          owner: renameScope(named.owner) as BackofficeRootOwner<{\n            organization: TOrganization;\n            project: TProject;\n          }>,\n          appId: named.appId,\n        };\n      case \"project\":\n        return {\n          kind: \"project\",\n          ...map.project(named as unknown as ProjectNamesOf<TScope>),\n          owner: renameScope(named.owner) as BackofficeProjectOwner<{\n            organization: TOrganization;\n            project: TProject;\n          }>,\n        };\n      default:\n        throw new Error(\"Unsupported Backoffice scope kind.\", { cause: named satisfies never });\n    }\n  }\n}\n\nexport function backofficeContextScopesEqual(\n  left: BackofficeContextScope,\n  right: BackofficeContextScope,\n): boolean {\n  // The path segment names a scope exactly, so equal segments mean equal scopes.\n  return backofficeScopePathSegment(left) === backofficeScopePathSegment(right);\n}\n\n/**\n * A scope restriction is an upper bound: a project's owner contains the project. Containment does\n * not chain, so an organization contains neither its apps' workspaces nor their projects.\n */\nexport function backofficeScopeContains(\n  restriction: BackofficeContextScope,\n  target: BackofficeContextScope,\n): boolean {\n  return (\n    backofficeContextScopesEqual(restriction, target) ||\n    (target.kind === \"project\" && backofficeContextScopesEqual(restriction, target.owner))\n  );\n}\n\nconst INVALID_BACKOFFICE_SCOPE = \"INVALID_BACKOFFICE_SCOPE\";\n\n/** A scope could not be read from untrusted text, such as a URL. */\nexport class BackofficeScopeParseError extends Error {\n  readonly code = INVALID_BACKOFFICE_SCOPE;\n\n  constructor(message: string) {\n    super(message);\n    this.name = \"BackofficeScopeParseError\";\n  }\n}\n\n/** Matches by code too, because errors lose their class across module copies and RPC. */\nexport function isBackofficeScopeParseError(error: unknown): error is BackofficeScopeParseError {\n  return (\n    error instanceof BackofficeScopeParseError ||\n    (typeof error === \"object\" &&\n      error !== null &&\n      \"code\" in error &&\n      error.code === INVALID_BACKOFFICE_SCOPE)\n  );\n}\n\n/** How one of a scope's names is written in text, and what a parse error calls it. */\nexport type BackofficeNameCodec<TName extends object> = {\n  label: string;\n  format(name: TName): string;\n  parse(value: string): TName;\n};\n\nexport type BackofficeScopeCodec<TNames extends BackofficeScopeNames> = {\n  organization: BackofficeNameCodec<TNames[\"organization\"]>;\n  project: BackofficeNameCodec<TNames[\"project\"]>;\n};\n\nconst organizationIdCodec: BackofficeNameCodec<{ orgId: string }> = {\n  label: \"org id\",\n  format: (name) => name.orgId,\n  parse: (orgId) => ({ orgId }),\n};\n\nconst projectIdCodec: BackofficeNameCodec<{ projectId: string }> = {\n  label: \"project id\",\n  format: (name) => name.projectId,\n  parse: (projectId) => ({ projectId }),\n};\n\nexport const backofficeOrganizationSlugCodec: BackofficeNameCodec<{ orgSlug: string }> = {\n  label: \"organization slug\",\n  format: (name) => name.orgSlug,\n  parse: (orgSlug) => ({ orgSlug }),\n};\n\nexport const backofficeScopeIdCodec: BackofficeScopeCodec<BackofficeScopeIdNames> = {\n  organization: organizationIdCodec,\n  project: projectIdCodec,\n};\n\nexport const backofficePublicScopeCodec: BackofficeScopeCodec<BackofficeScopePublicNames> = {\n  organization: backofficeOrganizationSlugCodec,\n  project: projectIdCodec,\n};\n\n/**\n * Names a scope in one URL path segment, e.g. `project:org:<org>:<projectId>`: app and project\n * scopes embed their owner's segment. Components are URI-encoded, so `:` only ever separates them.\n */\nexport function formatBackofficeScopeSegment<TNames extends BackofficeScopeNames>(\n  scope: BackofficeScope<TNames>,\n  codec: BackofficeScopeCodec<TNames>,\n): string {\n  switch (scope.kind) {\n    case \"system\":\n      return \"system\";\n    case \"org\":\n      return `org:${encodeURIComponent(codec.organization.format(scope))}`;\n    case \"user\":\n      return `user:${encodeURIComponent(scope.userId)}`;\n    case \"app\":\n      return `app:${formatBackofficeScopeSegment<TNames>(scope.owner, codec)}:${encodeURIComponent(scope.appId)}`;\n    case \"project\":\n      return `project:${formatBackofficeScopeSegment<TNames>(scope.owner, codec)}:${encodeURIComponent(codec.project.format(scope))}`;\n    default:\n      throw new Error(\"Unsupported Backoffice scope kind.\", { cause: scope satisfies never });\n  }\n}\n\n/** Reads a segment written by `formatBackofficeScopeSegment`; anything else is a parse error. */\nexport function parseBackofficeScopeSegment<TNames extends BackofficeScopeNames>(\n  segment: string,\n  codec: BackofficeScopeCodec<TNames>,\n): BackofficeScope<TNames> {\n  const components = segment.split(\":\");\n  let next = 0;\n  const scope = readScope();\n  if (next !== components.length) {\n    throw new BackofficeScopeParseError(\n      `${scopeLabel(scope.kind)} scope has unexpected components after it.`,\n    );\n  }\n  return scope;\n\n  // Reads one scope from the components, leaving those after it for an enclosing scope.\n  function readScope(): BackofficeScope<TNames> {\n    const kind = components[next++];\n    switch (kind) {\n      case \"system\":\n        return { kind: \"system\" };\n      case \"org\":\n        return {\n          kind: \"org\",\n          ...codec.organization.parse(readComponent(codec.organization.label)),\n        } as BackofficeOrganizationScope<TNames>;\n      case \"user\":\n        return { kind: \"user\", userId: readComponent(\"user id\") };\n      case \"app\": {\n        const owner = readOwner(\"App\");\n        if (owner.kind !== \"org\" && owner.kind !== \"user\") {\n          throw new BackofficeScopeParseError(`${scopeLabel(owner.kind)} scope cannot own an app.`);\n        }\n        return { kind: \"app\", owner, appId: readComponent(\"app id\") };\n      }\n      case \"project\": {\n        const owner = readOwner(\"Project\");\n        if (owner.kind === \"system\" || owner.kind === \"project\") {\n          throw new BackofficeScopeParseError(\n            `${scopeLabel(owner.kind)} scope cannot own a project.`,\n          );\n        }\n        return {\n          kind: \"project\",\n          owner,\n          ...codec.project.parse(readComponent(codec.project.label)),\n        };\n      }\n      default:\n        throw new BackofficeScopeParseError(`Unknown scope kind '${kind ?? \"\"}'.`);\n    }\n  }\n\n  function readOwner(ownedLabel: string): BackofficeScope<TNames> {\n    if (next === components.length) {\n      throw new BackofficeScopeParseError(`${ownedLabel} scope requires an owner scope.`);\n    }\n    return readScope();\n  }\n\n  function readComponent(label: string): string {\n    const value = components[next++];\n    if (value === undefined) {\n      throw new BackofficeScopeParseError(`Missing ${label}.`);\n    }\n    return decodeSegmentComponent(value, label);\n  }\n}\n\nfunction decodeSegmentComponent(value: string, label: string): string {\n  let decoded: string;\n  try {\n    decoded = decodeURIComponent(value);\n  } catch {\n    throw new BackofficeScopeParseError(`Invalid ${label} encoding.`);\n  }\n  if (!decoded) {\n    throw new BackofficeScopeParseError(`Missing ${label}.`);\n  }\n  return decoded;\n}\n\nfunction scopeLabel(kind: BackofficeContextScope[\"kind\"]): string {\n  switch (kind) {\n    case \"system\":\n      return \"System\";\n    case \"org\":\n      return \"Org\";\n    case \"user\":\n      return \"User\";\n    case \"app\":\n      return \"App\";\n    case \"project\":\n      return \"Project\";\n    default:\n      throw new Error(\"Unsupported Backoffice scope kind.\", { cause: kind satisfies never });\n  }\n}\n\n/**\n * Escapes scope text for a URL path segment that a router decodes once before it is parsed. Paths\n * allow a literal `:`, so the separator stays readable; a `:` inside a component was already\n * escaped when the segment was formatted.\n */\nexport function encodeBackofficeScopeForPath(text: string): string {\n  return encodeURIComponent(text).replaceAll(\"%3A\", \":\");\n}\n\n/** Names a scope in two URL path segments, `<kind>/<id>`, e.g. `project/org:acme:website`. */\nexport function formatBackofficeScopeRoutePath<TNames extends BackofficeScopeNames>(\n  scope: BackofficeScope<TNames>,\n  codec: BackofficeScopeCodec<TNames>,\n): string {\n  if (scope.kind === \"system\") {\n    return \"system/system\";\n  }\n  const components = formatBackofficeScopeSegment(scope, codec).slice(scope.kind.length + 1);\n  return `${scope.kind}/${encodeBackofficeScopeForPath(components)}`;\n}\n\n/** Reads the decoded `<kind>/<id>` route parameters written by `formatBackofficeScopeRoutePath`. */\nexport function parseBackofficeScopeRouteParams<TNames extends BackofficeScopeNames>(\n  params: { scopeKind: string; scopeId: string },\n  codec: BackofficeScopeCodec<TNames>,\n): BackofficeScope<TNames> {\n  if (params.scopeKind === \"system\") {\n    if (params.scopeId !== \"system\") {\n      throw new BackofficeScopeParseError(\"System scope requires the system id.\");\n    }\n    return { kind: \"system\" };\n  }\n  return parseBackofficeScopeSegment(`${params.scopeKind}:${params.scopeId}`, codec);\n}\n\n/** Names an ID-backed scope in one URL path segment, as the Backoffice API addresses scopes. */\nexport function backofficeScopePathSegment(scope: BackofficeContextScope): string {\n  return formatBackofficeScopeSegment(scope, backofficeScopeIdCodec);\n}\n\n/** Reads a segment written by `backofficeScopePathSegment`; anything else is a parse error. */\nexport function parseBackofficeScopePathSegment(segment: string): BackofficeContextScope {\n  return parseBackofficeScopeSegment(segment, backofficeScopeIdCodec);\n}\n"],"mappings":"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"}