@sanity/workbench 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/core/canvases.ts

@@ -0,0 +1,92 @@
+import type { CanvasResource as ProtocolCanvasResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import { AbstractApplication } from "./applications/application";
+import { getSanityDomain } from "./env";
+import { OrganizationId } from "./organizations";
+
+/**
+ * Canvas ID schema, branded for type safety.
+ * @public
+ */
+const CanvasId = z.string().nonempty().brand("CanvasId");
+
+/**
+ * Canvas ID type, branded for type safety.
+ * @public
+ */
+export type CanvasId = z.output<typeof CanvasId>;
+
+/**
+ * Validates and brands a string as a CanvasId.
+ * @public
+ */
+export function brandCanvasId(id: string): CanvasId {
+  return CanvasId.parse(id);
+}
+
+const Canvas = z.object({
+  id: CanvasId,
+  organizationId: OrganizationId,
+  status: z.enum(["active", "provisioning"]),
+});
+
+/**
+ * Represents a Canvas resource as returned from the API.
+ * @public
+ */
+export type Canvas = z.output<typeof Canvas>;
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Canvas.
+ * @public
+ */
+export function parseCanvas(data: unknown): Canvas {
+  return Canvas.parse(data);
+}
+
+/**
+ * Whilst the constructor takes an organization's canvas resource the existance
+ * therefore implies the organization has access to the canvas application which
+ * is what workbench most importantly wants to know.
+ * @public
+ */
+export class CanvasApplication extends AbstractApplication<"canvas"> {
+  readonly canvas: Canvas;
+
+  constructor(canvas: Canvas) {
+    super("canvas");
+
+    this.canvas = canvas;
+  }
+
+  get id(): CanvasId {
+    return this.canvas.id;
+  }
+
+  get href(): string {
+    return "canvas";
+  }
+
+  get title(): string {
+    return "Canvas";
+  }
+
+  get url(): URL {
+    return new URL(
+      `https://canvas.${getSanityDomain()}/o/${this.canvas.organizationId}`,
+    );
+  }
+
+  get isFederated(): boolean {
+    return false;
+  }
+
+  toProtocolResource(): ProtocolCanvasResource {
+    return {
+      type: "canvas",
+      id: this.id,
+    } satisfies ProtocolCanvasResource;
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,34 @@
+import type { OrganizationId } from "./organizations";
+
+/**
+ * Workbench configuration.
+ *
+ * @public
+ */
+interface Config {
+  /**
+   * The organization ID to use when rendering the workbench.
+   */
+  organizationId?: string;
+}
+
+/**
+ * The resolved configuration after processing
+ * and validating the provided config.
+ *
+ * @public
+ */
+type ResolvedConfig = Omit<Config, "organizationId"> & {
+  organizationId: OrganizationId;
+};
+
+/**
+ * Options for rendering a remote module, such as a user application.
+ *
+ * @public
+ */
+interface RemoteModuleRenderOptions {
+  reactStrictMode?: boolean;
+}
+
+export type { Config, ResolvedConfig, RemoteModuleRenderOptions };

package/src/core/env.ts

@@ -0,0 +1,43 @@
+declare const __SANITY_STAGING__: boolean | undefined;
+
+/**
+ * Returns the Sanity domain based on the `__SANITY_STAGING__` runtime-time flag.
+ * If the flag is set to `true`, the staging domain is returned.
+ * Otherwise, the production domain is returned.
+ *
+ * @public
+ */
+export function getSanityDomain(): string {
+  if (getSanityEnv() === "staging") {
+    return "sanity.work";
+  }
+  return "sanity.io";
+}
+
+/**
+ * Returns the API host based on the `__SANITY_STAGING__` runtime-time flag.
+ * If the flag is set to `true`, the staging API host is returned.
+ * Otherwise, the production API host is returned.
+ *
+ * @public
+ */
+export function getApiHost(): string | undefined {
+  return `https://api.${getSanityDomain()}`;
+}
+
+/**
+ * Returns the current Sanity environment based on the `__SANITY_STAGING__` runtime-time flag.
+ * If the flag is set to `true`, "staging" is returned.
+ * Otherwise, "production" is returned.
+ *
+ * @public
+ */
+export function getSanityEnv(): "staging" | "production" {
+  if (
+    typeof __SANITY_STAGING__ !== "undefined" &&
+    __SANITY_STAGING__ === true
+  ) {
+    return "staging";
+  }
+  return "production";
+}

package/src/core/index.ts

@@ -0,0 +1,13 @@
+export * from "./applications/application";
+export * from "./applications/application-list";
+export * from "./canvases";
+export * from "./config";
+export * from "./env";
+export * from "./log";
+export * from "./media-libraries";
+export * from "./organizations";
+export * from "./projects";
+export { joinUrlPaths } from "./shared/urls";
+export * from "./user-applications/core-app";
+export * from "./user-applications/studios";
+export * from "./user-applications/user-application";

package/src/core/log/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Log levels in order of verbosity (least to most)
+ * - none: Silent
+ * - error: Critical failures that prevent operation
+ * - warn: Issues that may cause problems but don't stop execution
+ * - info: High-level informational messages (default)
+ * - debug: Detailed debugging information (maintainer level)
+ * - trace: Very detailed tracing — sets `internal: true` on context
+ * @public
+ */
+export type LogLevel = "none" | "error" | "warn" | "info" | "debug";
+
+/**
+ * Namespaces organize logs by functional domain.
+ * @internal
+ */
+export type LogNamespace = string;
+
+type LogContext = { [key: string]: unknown };
+
+/**
+ * @public
+ */
+export interface Logger {
+  error: (message: string, context?: LogContext) => void;
+  warn: (message: string, context?: LogContext) => void;
+  info: (message: string, context?: LogContext) => void;
+  debug: (message: string, context?: LogContext) => void;
+}
+
+const LEVELS: readonly LogLevel[] = ["none", "error", "warn", "info", "debug"];
+
+interface LoggerOptions {
+  namespace?: LogNamespace;
+  context?: LogContext;
+  logLevel?: LogLevel;
+}
+
+/**
+ * @public
+ */
+export function createLogger({
+  namespace,
+  context: baseContext,
+  logLevel = "info",
+}: LoggerOptions = {}): Logger {
+  function isLevelEnabled(level: LogLevel): boolean {
+    return LEVELS.indexOf(level) <= LEVELS.indexOf(logLevel);
+  }
+
+  function logAtLevel(
+    level: LogLevel,
+    message: string,
+    context?: LogContext,
+  ): void {
+    if (!isLevelEnabled(level)) return;
+
+    const merged =
+      (baseContext ?? context) ? { ...baseContext, ...context } : undefined;
+    const args: unknown[] = [
+      ...(namespace ? [`[${namespace}]`] : []),
+      message,
+      ...(merged ? [merged] : []),
+    ];
+
+    if (level === "error") console.error(...args);
+    else if (level === "warn") console.warn(...args);
+    // oxlint-disable-next-line no-console
+    else if (level === "info") console.info(...args);
+    // oxlint-disable-next-line no-console
+    else console.debug(...args);
+  }
+
+  return {
+    error: (message, context) => logAtLevel("error", message, context),
+    warn: (message, context) => logAtLevel("warn", message, context),
+    info: (message, context) => logAtLevel("info", message, context),
+    debug: (message, context) => logAtLevel("debug", message, context),
+  };
+}
+
+/**
+ * Shared workbench logger instance. Use this from both the workbench host
+ * and its remotes so lifecycle and diagnostic logs appear under a single
+ * namespace.
+ *
+ * @public
+ */
+export const logger: Logger = createLogger({
+  namespace: "sanity-workbench",
+  logLevel: "debug",
+});

package/src/core/media-libraries.ts

@@ -0,0 +1,93 @@
+import type { MediaResource as ProtocolMediaResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import { AbstractApplication } from "./applications/application";
+import { getSanityDomain } from "./env";
+import { OrganizationId } from "./organizations";
+
+/**
+ * Canvas ID schema, branded for type safety.
+ * @public
+ */
+const MediaLibraryId = z.string().nonempty().brand("MediaLibraryId");
+
+/**
+ * MediaLibrary ID type, branded for type safety.
+ * @public
+ */
+export type MediaLibraryId = z.output<typeof MediaLibraryId>;
+
+/**
+ * Validates and brands a string as a MediaLibraryId.
+ * @public
+ */
+export function brandMediaLibraryId(id: string): MediaLibraryId {
+  return MediaLibraryId.parse(id);
+}
+
+const MediaLibrary = z.object({
+  id: MediaLibraryId,
+  organizationId: OrganizationId,
+  status: z.enum(["active", "provisioning"]),
+  aclMode: z.enum(["private", "public"]),
+});
+
+/**
+ * Represents a MediaLibrary resource as returned from the API.
+ * @public
+ */
+export type MediaLibrary = z.output<typeof MediaLibrary>;
+
+/**
+ * Validates and parses a raw API response into a branded
+ * MediaLibrary.
+ * @public
+ */
+export function parseMediaLibrary(data: unknown): MediaLibrary {
+  return MediaLibrary.parse(data);
+}
+
+/**
+ * Whilst the constructor takes an organization's media library resource the existance
+ * therefore implies the organization has access to the media library application which
+ * is what workbench most importantly wants to know.
+ * @public
+ */
+export class MediaLibraryApplication extends AbstractApplication<"media-library"> {
+  readonly library: MediaLibrary;
+
+  constructor(library: MediaLibrary) {
+    super("media-library");
+
+    this.library = library;
+  }
+
+  get id(): string {
+    return this.library.id;
+  }
+
+  get href(): string {
+    return "media";
+  }
+
+  get title(): string {
+    return "Media Library";
+  }
+
+  get isFederated(): boolean {
+    return false;
+  }
+
+  get url(): URL {
+    return new URL(
+      `https://media.${getSanityDomain()}/${this.library.organizationId}`,
+    );
+  }
+
+  toProtocolResource(): ProtocolMediaResource {
+    return {
+      type: "media-library",
+      id: this.id,
+    } satisfies ProtocolMediaResource;
+  }
+}

package/src/core/organizations.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+
+/**
+ * Organization ID schema, branded for type safety.
+ * @public
+ */
+export const OrganizationId = z.string().nonempty().brand("OrganizationId");
+
+/**
+ * Organization ID type, branded for type safety.
+ * @public
+ */
+export type OrganizationId = z.output<typeof OrganizationId>;
+
+/**
+ * Validates and brands a string as an OrganizationId.
+ * @public
+ */
+export function brandOrganizationId(id: string): OrganizationId {
+  return OrganizationId.parse(id);
+}
+
+const OrganizationMember = z.object({
+  sanityUserId: z.string(),
+  isCurrentUser: z.boolean(),
+  user: z.object({
+    id: z.string(),
+    displayName: z.string(),
+    familyName: z.string(),
+    givenName: z.string(),
+    middleName: z.string().nullable(),
+    imageUrl: z.string().nullable(),
+    email: z.string(),
+    loginProvider: z.string(),
+  }),
+  roles: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string(),
+      description: z.string().optional(),
+    }),
+  ),
+});
+
+/**
+ * @public
+ */
+export type OrganizationMember = z.output<typeof OrganizationMember>;
+
+/**
+ * Organization schema — validates and brands API responses
+ * from the `/organizations/:id` endpoint.
+ * @public
+ */
+export const Organization = z.object({
+  id: OrganizationId,
+  name: z.string(),
+  slug: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  dashboardStatus: z.enum(["enabled", "disabled"]),
+  aiFeaturesStatus: z.enum(["enabled", "disabled"]),
+  defaultRoleName: z.string(),
+});
+
+/**
+ * Represents an organization with optional members and
+ * features arrays depending on the generic parameters.
+ * - `Organization` — base fields only (default)
+ * - `Organization<true>` — includes `members`
+ * - `Organization<true, true>` — includes both
+ * @public
+ */
+export type Organization<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = z.output<typeof Organization> &
+  (IncludeMembers extends true ? { members: OrganizationMember[] } : unknown) &
+  (IncludeFeatures extends true ? { features: string[] } : unknown);
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Organization. The options control which schema is used —
+ * matching what the API returns based on query params.
+ * @public
+ */
+export function parseOrganization<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  data: unknown,
+  options?: {
+    includeMembers?: IncludeMembers;
+    includeFeatures?: IncludeFeatures;
+  },
+): Organization<IncludeMembers, IncludeFeatures> {
+  const includeMembers = options?.includeMembers ?? true;
+  const includeFeatures = options?.includeFeatures ?? true;
+
+  const extensions = {
+    ...(includeMembers && {
+      members: z.array(OrganizationMember),
+    }),
+    ...(includeFeatures && {
+      features: z.array(z.string()),
+    }),
+  };
+
+  const schema =
+    Object.keys(extensions).length > 0
+      ? Organization.extend(extensions)
+      : Organization;
+
+  return schema.parse(data) as Organization<IncludeMembers, IncludeFeatures>;
+}

package/src/core/projects.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+
+import { OrganizationId } from "./organizations";
+
+/**
+ * Project ID schema, branded for type safety.
+ * @public
+ */
+export const ProjectId = z.string().nonempty().brand("ProjectId");
+
+/**
+ * Project ID type, branded for type safety.
+ * @public
+ */
+export type ProjectId = z.output<typeof ProjectId>;
+
+/**
+ * Validates and brands a string as a ProjectId.
+ * @public
+ */
+export function brandProjectId(id: string): ProjectId {
+  return ProjectId.parse(id);
+}
+
+const ProjectMember = z.object({
+  id: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  isCurrentUser: z.boolean(),
+  isRobot: z.boolean(),
+  roles: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string(),
+      description: z.string(),
+    }),
+  ),
+});
+
+/**
+ * @public
+ */
+export type ProjectMember = z.output<typeof ProjectMember>;
+
+/**
+ * Project schema — validates and brands API responses
+ * from the `/projects/:id` endpoint.
+ * @public
+ */
+export const Project = z.object({
+  id: ProjectId,
+  displayName: z.string(),
+  studioHost: z.string().nullable(),
+  organizationId: OrganizationId,
+  metadata: z.object({
+    color: z.string().optional(),
+    externalStudioHost: z.string().optional(),
+    initialTemplate: z.string().optional(),
+    cliInitializedAt: z.string().optional(),
+    integration: z.literal(["manage", "cli"]),
+  }),
+  isBlocked: z.boolean(),
+  isDisabled: z.boolean(),
+  isDisabledByUser: z.boolean(),
+  activityFeedEnabled: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Represents a Sanity project with optional members and
+ * features arrays depending on the generic parameters.
+ * By default, neither members nor features are included.
+ * - `Project` — base fields only (default)
+ * - `Project<true>` — includes `members`
+ * - `Project<true, true>` — includes both
+ * @public
+ */
+export type Project<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = z.output<typeof Project> &
+  (IncludeMembers extends true ? { members: ProjectMember[] } : unknown) &
+  (IncludeFeatures extends true ? { features: string[] } : unknown);
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Project. The options control which schema is used —
+ * matching what the API returns based on query params.
+ * @public
+ */
+export function parseProject<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  data: unknown,
+  options?: {
+    includeMembers?: IncludeMembers;
+    includeFeatures?: IncludeFeatures;
+  },
+): Project<IncludeMembers, IncludeFeatures> {
+  const includeMembers = options?.includeMembers ?? true;
+  const includeFeatures = options?.includeFeatures ?? true;
+
+  const extensions = {
+    ...(includeMembers && { members: z.array(ProjectMember) }),
+    ...(includeFeatures && { features: z.array(z.string()) }),
+  };
+
+  const schema =
+    Object.keys(extensions).length > 0 ? Project.extend(extensions) : Project;
+
+  return schema.parse(data) as Project<IncludeMembers, IncludeFeatures>;
+}