@manta-eu/client 0.1.9 → 0.1.10

package/src/graphql-clients.ts

@@ -0,0 +1,67 @@
+import { ClientError, GraphQLClient } from "graphql-request";
+
+// Default client constructors for the v1 and Manta GraphQL APIs
+
+export const operatorRoleHeaders = { "x-hasura-role": "operator" } as const;
+
+export const v1GQLPath = "/v1/graphql";
+
+// To use custom keycloak headers, use headers: { "X-Keycloak-Token": keycloakToken } instead of credentials
+export function v1GraphQLClient(baseUrl: URL) {
+  const url = new URL(v1GQLPath, baseUrl);
+  return new GraphQLClient(url.toString(), {
+    credentials: "include",
+  });
+}
+
+export const mantaGQLPath = "/graphql";
+
+// A bearer is the credential: sending cookies with it needs credentialed CORS, which only trusted origins get.
+export function mantaGraphQLCredentials(headers?: Record<string, string>): RequestCredentials {
+  const sendsBearer = Object.keys(headers ?? {}).some((name) => name.toLowerCase() === "authorization");
+  return sendsBearer ? "omit" : "include";
+}
+
+/** Called before every request; a source that can also `renew()` is renewed before the one retry a 401 earns. */
+export type AccessTokenSource = (() => Promise<string>) & { renew?: (rejected?: string) => void };
+
+export type MantaGraphQLClientOptions = { getAccessToken?: AccessTokenSource };
+
+export function bearerFetch(getAccessToken: AccessTokenSource, fetchImpl?: typeof fetch): typeof fetch {
+  const send = async (input: RequestInfo | URL, init: RequestInit | undefined, token: string) => {
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    return (fetchImpl ?? globalThis.fetch)(input, { ...init, headers, credentials: "omit" });
+  };
+
+  return async (input, init) => {
+    const token = await getAccessToken();
+    const response = await send(input, init, token);
+    if (response.status !== 401) return response;
+
+    getAccessToken.renew?.(token);
+    return send(input, init, await getAccessToken());
+  };
+}
+
+export function mantaGraphQLClient(
+  baseUrl: URL,
+  onUnauthorized?: () => void,
+  headers?: Record<string, string>,
+  options?: MantaGraphQLClientOptions,
+) {
+  const url = new URL(mantaGQLPath, baseUrl);
+  const getAccessToken = options?.getAccessToken;
+  return new GraphQLClient(url.toString(), {
+    credentials: getAccessToken ? "omit" : mantaGraphQLCredentials(headers),
+    headers,
+    ...(getAccessToken ? { fetch: bearerFetch(getAccessToken) } : {}),
+    responseMiddleware: onUnauthorized
+      ? (response) => {
+          if (response instanceof ClientError && response.response.status === 401) {
+            onUnauthorized();
+          }
+        }
+      : undefined,
+  });
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./generated/graphql";
+export * from "./graphql-clients";

package/src/shared/action-document.ts

@@ -0,0 +1,56 @@
+import jsonld from "jsonld";
+import { encodeEntity, type Lens, type Schema } from "ldkit";
+import { xsd } from "ldkit/namespaces";
+
+export type DocumentTerm = { value: string; termType: string };
+
+export type DocumentQuad = {
+  subject: DocumentTerm;
+  predicate: { value: string };
+  object: DocumentTerm & { datatype?: { value: string }; language?: string };
+};
+
+export type InsertEntity<S extends Schema> = Parameters<Lens<S>["insert"]>[number];
+
+// jsonld keeps the `_:` prefix in a blank node value
+function jsonldTerm(term: DocumentTerm): DocumentTerm {
+  return { termType: term.termType, value: term.termType === "BlankNode" ? `_:${term.value}` : term.value };
+}
+
+function jsonldQuad(quad: DocumentQuad) {
+  const { subject, predicate, object } = quad;
+
+  return {
+    subject: jsonldTerm(subject),
+    predicate: { termType: "NamedNode", value: predicate.value },
+    object:
+      object.termType === "Literal"
+        ? {
+            termType: "Literal",
+            value: object.value,
+            language: object.language,
+            datatype: { value: object.datatype?.value ?? xsd.string },
+          }
+        : jsonldTerm(object),
+    graph: { termType: "DefaultGraph", value: "" },
+  };
+}
+
+export async function documentFromQuads(
+  quads: readonly DocumentQuad[],
+  subjectIri: string,
+): Promise<Record<string, unknown>> {
+  const described = quads.filter(({ subject }) => subject.value === subjectIri || subject.termType === "BlankNode");
+  const flattened = await jsonld.fromRDF(described.map(jsonldQuad));
+
+  return jsonld.frame(flattened, { "@id": subjectIri, "@embed": "@always" });
+}
+
+export function entityActionDocument<S extends Schema>(
+  schema: S,
+  entity: InsertEntity<S>,
+): Promise<Record<string, unknown>> {
+  const quads = encodeEntity(schema, entity).filter((quad) => quad.object.termType !== "Variable");
+
+  return documentFromQuads(quads, entity.$id);
+}

package/src/shared/action-plan.ts

@@ -0,0 +1 @@
+export { isActionPlanGraphIri } from "@manta-eu/rdf-lib/namespaces";

package/src/shared/agent-mode.ts

@@ -0,0 +1,46 @@
+import { splitIdentifierWords } from "@manta-eu/lib/identifier-words";
+import { baseIri, iriLocalName } from "./rdf-namespaces";
+
+export function humanizeEntityName(raw: string): string {
+  return splitIdentifierWords(raw);
+}
+
+export function humanizePlanName(raw: string): string {
+  return humanizeEntityName(raw.replace(/^ActionPlan_/, ""));
+}
+
+export function extractPlanName(iri: string): string {
+  const lastSlash = iri.lastIndexOf("/");
+  const lastHash = iri.lastIndexOf("#");
+  const lastSeparator = Math.max(lastSlash, lastHash);
+  if (lastSeparator > 0) {
+    return humanizePlanName(iri.slice(lastSeparator + 1));
+  }
+  return iri;
+}
+
+export function buildPlanIri(planName: string): string {
+  if (planName.startsWith("http://") || planName.startsWith("https://")) {
+    return planName;
+  }
+  return `${baseIri}${planName}`;
+}
+
+export function planGraphIriToFragment(iri: string) {
+  return iriLocalName(iri) || "";
+}
+
+export function buildPlanHref(iri: string) {
+  return `/plans/${encodeURIComponent(planGraphIriToFragment(iri))}`;
+}
+
+export function buildActivityIri(param: string): string {
+  if (param.startsWith("http://") || param.startsWith("https://")) {
+    return param;
+  }
+  return `${baseIri}${param}`;
+}
+
+export function buildActivityHref(iri: string) {
+  return `/activity/${encodeURIComponent(iriLocalName(iri) || iri)}`;
+}

package/src/shared/agent-types.ts

@@ -0,0 +1,46 @@
+import type { IRI } from "./rdf-namespaces";
+import type { ChatUIMessage } from "./index";
+
+export enum ChatContextKind {
+  RuleEdit = "RULE_EDIT",
+  RuleCreate = "RULE_CREATE",
+  Plan = "PLAN",
+}
+
+export type ChatContext =
+  | { kind: ChatContextKind.RuleEdit; ruleIri: IRI }
+  | { kind: ChatContextKind.RuleCreate; draftIri: IRI }
+  | { kind: ChatContextKind.Plan; planGraphIri: IRI };
+
+export function isDraftChatContext(context: ChatContext | undefined): boolean {
+  return context?.kind === ChatContextKind.RuleCreate;
+}
+
+export function isRuleScopedChatContext(context: ChatContext | undefined): boolean {
+  return context?.kind === ChatContextKind.RuleEdit || context?.kind === ChatContextKind.RuleCreate;
+}
+
+export type CachedMemorySchemaProperty = {
+  path: string;
+  label: string;
+  dataType: string;
+  required: boolean;
+  allowedValues: string[];
+  keyProperty: boolean;
+  inferred: boolean;
+};
+
+export type CachedMemorySchema = {
+  iri: string;
+  label: string;
+  description: string | null;
+  properties: CachedMemorySchemaProperty[];
+};
+
+export type ChatState = {
+  chatIRI: IRI;
+  context?: ChatContext;
+  contextTokens: number;
+};
+
+export type SendAgentMessage = (message: ChatUIMessage) => Promise<void>;

package/src/shared/chat-context.ts

@@ -0,0 +1,47 @@
+import { match } from "ts-pattern";
+import { v7 as uuidv7 } from "uuid";
+import { z } from "zod";
+import { extractPlanName, humanizeEntityName } from "./agent-mode";
+import { ChatContextKind, type ChatContext } from "./agent-types";
+import { expandPrefix, iriLocalName, type IRI } from "./rdf-namespaces";
+
+const storedChatContextSchema = z.object({
+  kind: z.enum(ChatContextKind),
+  iri: z
+    .string()
+    .min(1)
+    .transform((iri) => iri as IRI),
+});
+
+export function generateRuleDraftIri(): IRI {
+  return expandPrefix(`:RuleDraft_${uuidv7()}`);
+}
+
+export function contextChatName(context: ChatContext): string {
+  return match(context)
+    .with(
+      { kind: ChatContextKind.RuleEdit },
+      ({ ruleIri }) => `Edit rule: ${humanizeEntityName(iriLocalName(ruleIri).replace(/^Rule_/, ""))}`,
+    )
+    .with({ kind: ChatContextKind.RuleCreate }, () => "Create rule")
+    .with({ kind: ChatContextKind.Plan }, ({ planGraphIri }) => extractPlanName(planGraphIri))
+    .exhaustive();
+}
+
+export function chatContextIri(context: ChatContext): IRI {
+  return match(context)
+    .with({ kind: ChatContextKind.RuleEdit }, (c) => c.ruleIri)
+    .with({ kind: ChatContextKind.RuleCreate }, (c) => c.draftIri)
+    .with({ kind: ChatContextKind.Plan }, (c) => c.planGraphIri)
+    .exhaustive();
+}
+
+export function parseStoredChatContext(input: unknown): ChatContext {
+  const { kind, iri } = storedChatContextSchema.parse(input);
+
+  return match(kind)
+    .with(ChatContextKind.RuleEdit, (): ChatContext => ({ kind: ChatContextKind.RuleEdit, ruleIri: iri }))
+    .with(ChatContextKind.RuleCreate, (): ChatContext => ({ kind: ChatContextKind.RuleCreate, draftIri: iri }))
+    .with(ChatContextKind.Plan, (): ChatContext => ({ kind: ChatContextKind.Plan, planGraphIri: iri }))
+    .exhaustive();
+}

package/src/shared/chat-manager.ts

@@ -0,0 +1,197 @@
+import { z } from "zod/v4";
+import { ChatContextKind } from "./agent-types";
+import type { IRI } from "./rdf-namespaces";
+
+export const chatManagerBasePath = "agents/chat-manager";
+export const chatTicketPath = "agents/chat-ticket";
+export const chatTicketQueryParam = "chat_ticket";
+export const thinkChatFacetPath = "think-chat";
+export const defaultConversationName = "New chat";
+export const defaultFolderName = "New folder";
+
+export const chatManagerScopeSchema = z.strictObject({
+  version: z.literal(1),
+  realm: z.string().min(1),
+  datastoreId: z.string().min(1),
+  userId: z.string().min(1),
+});
+
+export type ChatManagerScope = z.infer<typeof chatManagerScopeSchema>;
+
+const shortTextMaxLength = 200;
+const descriptionMaxLength = 4000;
+
+const idSchema = z.uuid();
+export const chatIdSchema = idSchema;
+const iriSchema = z
+  .string()
+  .min(1)
+  .transform((iri) => iri as IRI);
+
+export const chatContextSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal(ChatContextKind.RuleEdit), ruleIri: iriSchema }),
+  z.strictObject({ kind: z.literal(ChatContextKind.RuleCreate), draftIri: iriSchema }),
+  z.strictObject({ kind: z.literal(ChatContextKind.Plan), planGraphIri: iriSchema }),
+]);
+
+export const chatManagerStateSchema = z.strictObject({
+  schemaVersion: z.literal(1),
+  scope: chatManagerScopeSchema.nullable(),
+  chatListRevision: z.number().int().nonnegative(),
+  lastRetentionCheckAt: z.iso.datetime().nullable().default(null),
+});
+
+export type ChatManagerState = z.infer<typeof chatManagerStateSchema>;
+
+export const conversationLifecycleStatusSchema = z.enum(["creating", "active", "deleting"]);
+export type ConversationLifecycleStatus = z.infer<typeof conversationLifecycleStatusSchema>;
+
+export const conversationSummarySchema = z.strictObject({
+  id: chatIdSchema,
+  chatIRI: z.string().min(1),
+  title: z.string().min(1),
+  context: chatContextSchema.nullable(),
+  folderId: idSchema.nullable(),
+  createdAt: z.iso.datetime(),
+  updatedAt: z.iso.datetime(),
+});
+
+export type ConversationSummary = z.infer<typeof conversationSummarySchema>;
+
+export const createConversationInputSchema = z.strictObject({
+  name: z.string().trim().min(1).max(shortTextMaxLength).optional(),
+  idempotencyKey: z.string().trim().min(1).max(shortTextMaxLength).optional(),
+});
+
+export type CreateConversationInput = z.input<typeof createConversationInputSchema>;
+
+export const contextConversationInputSchema = z.strictObject({
+  context: chatContextSchema,
+});
+
+export type ContextConversationInput = z.input<typeof contextConversationInputSchema>;
+
+export const reassignConversationContextInputSchema = z.strictObject({
+  context: chatContextSchema,
+  conversationId: chatIdSchema,
+});
+
+export type ReassignConversationContextInput = z.input<typeof reassignConversationContextInputSchema>;
+
+export const conversationIdInputSchema = z.strictObject({ id: chatIdSchema });
+export type ConversationIdInput = z.input<typeof conversationIdInputSchema>;
+
+export const renameConversationInputSchema = z.strictObject({
+  id: chatIdSchema,
+  title: z.string().trim().min(1).max(shortTextMaxLength),
+});
+
+export type RenameConversationInput = z.input<typeof renameConversationInputSchema>;
+
+const listInputSchema = z.strictObject({
+  search: z.string().trim().max(shortTextMaxLength).optional(),
+  orderBy: z.enum(["CREATED_AT", "UPDATED_AT"]).default("UPDATED_AT"),
+  limit: z.number().int().min(1).max(100).default(10),
+  offset: z.number().int().min(0).default(0),
+});
+
+export const listConversationsInputSchema = listInputSchema.extend({
+  folderId: idSchema.optional(),
+});
+
+export type ListConversationsInput = z.input<typeof listConversationsInputSchema>;
+
+export const deleteConversationResultSchema = z.discriminatedUnion("status", [
+  z.strictObject({ status: z.literal("deleted"), id: chatIdSchema }),
+  z.strictObject({ status: z.literal("not_found") }),
+]);
+
+export const folderSummarySchema = z.strictObject({
+  id: idSchema,
+  title: z.string().min(1).max(shortTextMaxLength),
+  description: z.string().max(descriptionMaxLength).nullable(),
+  createdAt: z.iso.datetime(),
+  updatedAt: z.iso.datetime(),
+});
+
+export type FolderSummary = z.infer<typeof folderSummarySchema>;
+
+export const createFolderInputSchema = z.strictObject({
+  title: z.string().trim().min(1).max(shortTextMaxLength).optional(),
+  description: z.string().trim().max(descriptionMaxLength).optional(),
+});
+
+export type CreateFolderInput = z.input<typeof createFolderInputSchema>;
+
+export const updateFolderInputSchema = z.strictObject({
+  id: idSchema,
+  title: z.string().trim().min(1).max(shortTextMaxLength).optional(),
+  description: z.string().trim().max(descriptionMaxLength).optional(),
+});
+
+export type UpdateFolderInput = z.input<typeof updateFolderInputSchema>;
+
+export const folderIdInputSchema = z.strictObject({ id: idSchema });
+export type FolderIdInput = z.input<typeof folderIdInputSchema>;
+
+export const listFoldersInputSchema = listInputSchema;
+
+export type ListFoldersInput = z.input<typeof listFoldersInputSchema>;
+
+export const assignConversationInputSchema = z.strictObject({
+  conversationId: chatIdSchema,
+  folderId: idSchema.nullable(),
+});
+
+export type AssignConversationInput = z.input<typeof assignConversationInputSchema>;
+
+export const deleteFolderResultSchema = z.discriminatedUnion("status", [
+  z.strictObject({ status: z.literal("deleted"), id: idSchema }),
+  z.strictObject({ status: z.literal("not_found") }),
+]);
+
+export type DeleteFolderResult = z.infer<typeof deleteFolderResultSchema>;
+
+export type DeleteConversationResult = z.infer<typeof deleteConversationResultSchema>;
+
+export const conversationConfigSchema = z.strictObject({
+  version: z.literal(1),
+  scope: chatManagerScopeSchema,
+  chatId: chatIdSchema,
+  chatIRI: z.string().min(1),
+  context: chatContextSchema.nullable(),
+});
+
+export type ConversationConfig = z.infer<typeof conversationConfigSchema>;
+
+export const thinkChatStateSchema = z.strictObject({
+  config: conversationConfigSchema.nullable(),
+  contextTokens: z.number().int().nonnegative(),
+  compacting: z.boolean().default(false),
+  automaticTitleGenerationComplete: z.boolean().default(false),
+});
+
+export type ThinkChatState = z.infer<typeof thinkChatStateSchema>;
+
+/**
+ * Browser-safe surface for the owner Agent. Keeping this contract separate
+ * from the Worker class prevents server-only types and internal RPC methods
+ * from entering the client bundle.
+ */
+export type ChatManagerClient = {
+  readonly state: ChatManagerState;
+  createConversation(input?: CreateConversationInput): Promise<ConversationSummary>;
+  findContextConversation(input: ContextConversationInput): Promise<ConversationSummary | null>;
+  ensureContextConversation(input: ContextConversationInput): Promise<ConversationSummary>;
+  reassignConversationContext(input: ReassignConversationContextInput): Promise<ConversationSummary>;
+  getConversation(input: ConversationIdInput): Promise<ConversationSummary | null>;
+  listConversations(input?: ListConversationsInput): Promise<ConversationSummary[]>;
+  renameConversation(input: RenameConversationInput): Promise<ConversationSummary | null>;
+  deleteConversation(input: ConversationIdInput): Promise<DeleteConversationResult>;
+  createFolder(input?: CreateFolderInput): Promise<FolderSummary>;
+  updateFolder(input: UpdateFolderInput): Promise<FolderSummary | null>;
+  getFolder(input: FolderIdInput): Promise<FolderSummary | null>;
+  listFolders(input?: ListFoldersInput): Promise<FolderSummary[]>;
+  deleteFolder(input: FolderIdInput): Promise<DeleteFolderResult>;
+  assignConversation(input: AssignConversationInput): Promise<ConversationSummary | null>;
+};

package/src/shared/chat-turn-errors.ts

@@ -0,0 +1,25 @@
+import { z } from "zod/v4";
+
+export const chatTurnErrorMessages = {
+  conversationScope: "This chat can't be used with the currently selected datastore.",
+  contextOverflow: "This chat has become too long to continue.",
+  messageNotSaved:
+    "Manta couldn't complete this response, and your message may not have been saved. Please send it again.",
+  unexpected: "Manta couldn't complete this response. Please try again.",
+} as const;
+
+export const chatTurnErrorMessageSchema = z.enum([
+  chatTurnErrorMessages.conversationScope,
+  chatTurnErrorMessages.contextOverflow,
+  chatTurnErrorMessages.messageNotSaved,
+  chatTurnErrorMessages.unexpected,
+]);
+
+export type ChatTurnErrorMessage = z.infer<typeof chatTurnErrorMessageSchema>;
+
+export function resolveChatTurnErrorMessage(error: unknown): ChatTurnErrorMessage {
+  const message = error instanceof Error ? error.message : error;
+  const parsed = chatTurnErrorMessageSchema.safeParse(message);
+
+  return parsed.success ? parsed.data : chatTurnErrorMessages.unexpected;
+}

package/src/shared/constants.ts

@@ -0,0 +1,17 @@
+// A realm slug. Which slugs exist is the deploying application's roster, injected into
+// @manta-eu/ldo at runtime - this package is published and must not name customers.
+export type { KeycloakRealm } from "@manta-eu/ldo/realm";
+
+export const selectedDatastoreCookieName = "selected-datastore";
+
+export const errorRoutePath = "/error";
+
+export const scheduleToolingFlagKey = "schedule-tooling-enabled";
+export const teamActivationFlagKey = "team-activation-enabled";
+export const memoryExtractionFlagKey = "memory-extraction-enabled";
+export const memoryAutoSupersedeFlagKey = "memory-auto-supersede-enabled";
+export const memoryReplayFlagKey = "memory-replay-enabled";
+export const memoryMaintenanceFlagKey = "memory-maintenance-enabled";
+
+// Gates "Remove"/"Restore" and "Show archived". Off: see wiki/infisical-secrets.md § Removal gap.
+export const enableDatastoreRemoval = false;

package/src/shared/conversation-starter-defaults.ts

@@ -0,0 +1,27 @@
+export type ConversationStarterDefault = {
+  id: string;
+  title: string;
+  description: string;
+  priority: number;
+};
+
+export const defaultConversationStarters: ConversationStarterDefault[] = [
+  {
+    id: "default-top-advertising-strategies",
+    title: "What were the top advertising strategies for Meta in 2025?",
+    description: "Explore the most effective Meta advertising tactics and trends from 2025.",
+    priority: 1,
+  },
+  {
+    id: "default-common-causes-of-ad-spend-waste",
+    title: "What are the 3 most common causes of ad spend waste?",
+    description: "Discover the biggest budget drains and how to avoid them.",
+    priority: 2,
+  },
+  {
+    id: "default-top-benefits-of-advertising-on-snapchat",
+    title: "Top benefits of advertising on Snapchat?",
+    description: "Learn why Snapchat could be a valuable addition to your ad mix.",
+    priority: 3,
+  },
+];

package/src/shared/datastore-id.ts

@@ -0,0 +1,25 @@
+export function slugify(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Org slug + full group path: "Demo Portfolio Co" + ["Vertical A","Team 1"] -> "demo-portfolio-co-vertical-a-team-1".
+export function deriveDatastoreId(organizationName: string, segments: string[]): string {
+  return (
+    [organizationName, ...segments]
+      .map(slugify)
+      // eslint-disable-next-line @manta-eu/prefer-is-present -- agents/vite.config.ts loads this file without lib
+      .filter((slug) => slug.length > 0)
+      .join("-")
+  );
+}
+
+// Validated before reaching Infisical/KGC/RDFox since the Keycloak attribute is admin-settable.
+const datastoreIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function isValidDatastoreId(id: string): boolean {
+  return datastoreIdPattern.test(id);
+}

package/src/shared/datastore-path.ts

@@ -0,0 +1,80 @@
+import { isValidDatastoreId } from "./datastore-id";
+
+export const datastoreRoutePrefix = "/d";
+
+export const datastoreHeaderName = "x-manta-datastore";
+
+export const datastoreQueryParam = "datastore";
+
+export const redirectRoutePath = "/redirect";
+
+export type DatastoreLocation = { datastoreId: string | undefined; path: string };
+
+const datastorePathPattern = new RegExp(`^${datastoreRoutePrefix}/([^/]+)(/.*)?$`);
+
+// "//evil.com" and "/\evil.com" both resolve off-origin - browsers treat "\" as "/" for special schemes.
+export function isRootRelativePath(url: string): boolean {
+  return url.startsWith("/") && !url.startsWith("//") && !url.startsWith("/\\");
+}
+
+export function datastoreBasename(datastoreId: string): string {
+  return `${datastoreRoutePrefix}/${encodeURIComponent(datastoreId)}`;
+}
+
+export function parseDatastorePath(pathname: string): DatastoreLocation {
+  const split = splitDatastorePath(pathname);
+  if (!split) return { datastoreId: undefined, path: pathname };
+
+  const datastoreId = safeDecode(split.segment);
+  if (!datastoreId || !isValidDatastoreId(datastoreId)) return { datastoreId: undefined, path: pathname };
+
+  return { datastoreId, path: split.rest };
+}
+
+export function datastoreRelativePath(pathname: string): string {
+  return splitDatastorePath(pathname)?.rest ?? pathname;
+}
+
+export function datastoreHeader(datastoreId: string | undefined): Record<string, string> {
+  return datastoreId ? { [datastoreHeaderName]: datastoreId } : {};
+}
+
+export function datastoreSocketQuery(datastoreId: string | undefined): Record<string, string> {
+  return datastoreId ? { [datastoreQueryParam]: datastoreId } : {};
+}
+
+export function withDatastoreQueryParam(href: string, datastoreId: string | undefined): string {
+  if (!datastoreId) return href;
+
+  const url = new URL(href, "http://placeholder");
+  url.searchParams.set(datastoreQueryParam, datastoreId);
+  return `${url.pathname}${url.search}${url.hash}`;
+}
+
+export function withDatastorePrefix(datastoreId: string, path: string): string {
+  return `${datastoreBasename(datastoreId)}${path}`;
+}
+
+export function datastoreScopedRoutePattern(path: string): string {
+  return `${datastoreRoutePrefix}/:datastoreId${path}`;
+}
+
+// Matches a path with or without its "/d/<id>/" prefix, for a Workbox denylist entry.
+export function datastoreScopedDenylist(pathWithoutSlash: string): RegExp {
+  return new RegExp(`^/(${datastoreRoutePrefix.slice(1)}/[^/]+/)?${pathWithoutSlash}\\b`);
+}
+
+function splitDatastorePath(pathname: string): { segment: string; rest: string } | undefined {
+  const match = datastorePathPattern.exec(pathname);
+  if (!match?.[1]) return undefined;
+
+  return { segment: match[1], rest: match[2] || "/" };
+}
+
+function safeDecode(segment: string): string | undefined {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return undefined;
+  }
+}