@withstudiocms/sdk 0.0.0-beta.0 → 0.1.0-beta.1

package/dist/index.js

@@ -0,0 +1,24 @@
+import { Deepmerge, Effect, Layer, Logger } from "@withstudiocms/effect";
+import CacheService from "./cache.js";
+import { DBClientLive, makeSDKContext } from "./context.js";
+import { makeLogger, setLoggerLevel } from "./lib/logger.js";
+import SDKModules from "./modules/index.js";
+export * from "./context.js";
+const loggerLayer = Logger.replace(Logger.defaultLogger, makeLogger);
+const SDKBaseDependencies = Layer.mergeAll(
+  CacheService.Default,
+  Deepmerge.Default,
+  setLoggerLevel,
+  loggerLayer
+);
+const StudioCMSSDKCore = Effect.all({
+  dbService: DBClientLive,
+  cache: CacheService,
+  ...SDKModules
+}).pipe(Effect.provide(SDKBaseDependencies));
+const makeStudioCMSSDKCoreLive = (context) => StudioCMSSDKCore.pipe(Effect.provide(makeSDKContext(context)));
+export {
+  SDKBaseDependencies,
+  StudioCMSSDKCore,
+  makeStudioCMSSDKCoreLive
+};

package/dist/lib/diff.d.ts

@@ -0,0 +1,39 @@
+import { Effect } from '@withstudiocms/effect';
+import { createTwoFilesPatch as diffCreateTwoFilesPatch } from 'diff';
+import { type Diff2HtmlConfig } from 'diff2html';
+declare const DiffError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DiffError";
+} & Readonly<A>;
+/**
+ * Custom error class for diff-related operations in the SDK.
+ */
+export declare class DiffError extends DiffError_base<{
+    cause: unknown;
+}> {
+}
+/**
+ * Helper function to wrap diff-related operations with error handling.
+ *
+ * @param _try - A function that performs the desired operation.
+ * @returns An Effect that either succeeds with the result of the operation or fails with a DiffError.
+ */
+export declare const useDiffError: <T>(_try: () => T) => Effect.Effect<T, DiffError, never>;
+/**
+ * Creates a unified diff patch between two text inputs.
+ *
+ * @param oldStr - The original text.
+ * @param newStr - The modified text.
+ * @param fileNameOld - The name of the original file (default: 'OldFile').
+ * @param fileNameNew - The name of the modified file (default: 'NewFile').
+ * @returns An Effect that resolves to the unified diff string.
+ */
+export declare const createTwoFilesPatch: <T>(fn: (patch: typeof diffCreateTwoFilesPatch) => T) => Effect.Effect<T, DiffError, never>;
+/**
+ * Generates an HTML representation of the differences between two text inputs.
+ *
+ * @param diff - The unified diff string.
+ * @param options - Optional configuration for the diff HTML output.
+ * @returns An Effect that resolves to the HTML string representing the diff.
+ */
+export declare const diffHTML: (diff: string, options?: Diff2HtmlConfig | undefined) => Effect.Effect<string, DiffError, never>;
+export {};

package/dist/lib/diff.js

@@ -0,0 +1,29 @@
+import { Data, Effect } from "@withstudiocms/effect";
+import { createTwoFilesPatch as diffCreateTwoFilesPatch } from "diff";
+import { html } from "diff2html";
+class DiffError extends Data.TaggedError("DiffError") {
+}
+const useDiffError = (_try) => Effect.try({
+  try: _try,
+  catch: (error) => new DiffError({ cause: error })
+});
+const createTwoFilesPatch = Effect.fn(
+  (fn) => useDiffError(() => fn(diffCreateTwoFilesPatch))
+);
+const diffHTML = Effect.fn(
+  (diff, options) => useDiffError(
+    () => html(diff, {
+      diffStyle: "word",
+      matching: "lines",
+      drawFileList: false,
+      outputFormat: "side-by-side",
+      ...options
+    })
+  )
+);
+export {
+  DiffError,
+  createTwoFilesPatch,
+  diffHTML,
+  useDiffError
+};

package/dist/lib/logger.d.ts

@@ -0,0 +1,31 @@
+import { Layer } from '@withstudiocms/effect';
+export declare function stripNameFromLabel(label: string): string;
+/**
+ * A cache that stores instances of `AstroIntegrationLogger` associated with their string keys.
+ * This is used to avoid creating multiple logger instances for the same key.
+ */
+export declare const loggerCache: Map<string, SDKLogger>;
+export type LoggerLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export declare const levels: Record<LoggerLevel, number>;
+export interface LogOptions {
+    level: LoggerLevel;
+}
+export declare const getEventPrefix: (level: LoggerLevel, label?: string) => string;
+export declare class SDKLogger {
+    options: LogOptions;
+    label: string;
+    constructor(logging: LogOptions, label: string);
+    /**
+     * Creates a new logger instance with a new label, but the same log options.
+     */
+    fork(label: string): SDKLogger;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+/**
+ * Sets the logger level based on the `STUDIOCMS_LOGLEVEL` environment variable,
+ * defaulting to `LogLevel.Info` if the variable is not set or invalid.
+ */
+export declare const setLoggerLevel: Layer.Layer<never, import("effect/ConfigError").ConfigError, never>;

package/dist/lib/logger.js

@@ -0,0 +1,131 @@
+import { styleText } from "node:util";
+import { Config, Effect, Layer, List, Logger, LogLevel } from "@withstudiocms/effect";
+function stripNameFromLabel(label) {
+  const prefix = "studiocms/";
+  return label.startsWith(prefix) ? label.slice(prefix.length) : label;
+}
+const loggerCache = /* @__PURE__ */ new Map();
+const levels = {
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  silent: 90
+};
+const dateTimeFormat = new Intl.DateTimeFormat([], {
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+  hour12: false
+});
+function getLevelPrefix(level) {
+  const levelLabel = level.toUpperCase();
+  switch (level) {
+    case "error":
+      return `[${levelLabel}]`;
+    case "warn":
+      return `[${levelLabel}]`;
+    case "debug":
+      return `[${levelLabel}]`;
+    default:
+      return "";
+  }
+}
+const getEventPrefix = (level, label) => {
+  const timestamp = `${dateTimeFormat.format(/* @__PURE__ */ new Date())}`;
+  const prefix = [];
+  if (level === "error" || level === "warn" || level === "debug") {
+    prefix.push(styleText("bold", timestamp));
+    prefix.push(getLevelPrefix(level));
+  } else {
+    prefix.push(timestamp);
+  }
+  if (label) {
+    prefix.push(`[${label}]`);
+  }
+  if (level === "error") {
+    return styleText("red", prefix.join(" "));
+  }
+  if (level === "warn") {
+    return styleText("yellow", prefix.join(" "));
+  }
+  if (level === "debug") {
+    return styleText("blue", prefix.join(" "));
+  }
+  if (prefix.length === 1) {
+    return styleText("dim", prefix[0]);
+  }
+  return `${styleText("dim", prefix[0])} ${styleText("blue", prefix.splice(1).join(" "))}`;
+};
+class SDKLogger {
+  options;
+  label;
+  constructor(logging, label) {
+    this.options = logging;
+    this.label = label;
+  }
+  /**
+   * Creates a new logger instance with a new label, but the same log options.
+   */
+  fork(label) {
+    return new SDKLogger(this.options, label);
+  }
+  info(message) {
+    console.log(`${getEventPrefix("info", this.label)} ${message}`);
+  }
+  warn(message) {
+    console.warn(`${getEventPrefix("warn", this.label)} \u26A0\uFE0F ${message}`);
+  }
+  error(message) {
+    console.error(`${getEventPrefix("error", this.label)} \u274C ${message}`);
+  }
+  debug(message) {
+    console.debug(`${getEventPrefix("debug", this.label)} \u{1F41B} ${message}`);
+  }
+}
+const _logger = new SDKLogger({ level: "info" }, "studiocms:runtime");
+const makeLogger = Logger.make(({ logLevel, message: _message, spans }) => {
+  const label = "sdk";
+  const logger = loggerCache.get(label) ?? _logger.fork(`studiocms:runtime/${stripNameFromLabel(label)}`);
+  loggerCache.set(label, logger);
+  const list = List.toArray(spans);
+  const spanPart = list.length ? ` :: ${list.join(" \u203A ")}` : "";
+  const message = `${String(_message)}${spanPart}`;
+  switch (logLevel) {
+    case LogLevel.Trace:
+    case LogLevel.Debug: {
+      logger.debug(`${message}`);
+      break;
+    }
+    case LogLevel.Error:
+    case LogLevel.Fatal: {
+      logger.error(`${message}`);
+      break;
+    }
+    case LogLevel.Warning: {
+      logger.warn(`${message}`);
+      break;
+    }
+    case LogLevel.All:
+    case LogLevel.Info: {
+      logger.info(message);
+      break;
+    }
+    default: {
+      logger.info(message);
+    }
+  }
+});
+const setLoggerLevel = Config.withDefault(
+  Config.logLevel("STUDIOCMS_LOGLEVEL"),
+  LogLevel.Info
+).pipe(Effect.andThen(Logger.minimumLogLevel), Layer.unwrapEffect);
+export {
+  SDKLogger,
+  getEventPrefix,
+  levels,
+  loggerCache,
+  makeLogger,
+  setLoggerLevel,
+  stripNameFromLabel
+};

package/dist/lib/pluginUtils.d.ts

@@ -0,0 +1,221 @@
+import { Effect, Schema } from '@withstudiocms/effect';
+import type { StudioCMSPluginData } from '@withstudiocms/kysely/tables';
+import type { z } from 'zod';
+/**
+ * Represents a plugin data entry with a strongly-typed `data` property.
+ *
+ * @template T - The type of the `data` property.
+ * @property {T} data - The plugin-specific data payload.
+ */
+export interface PluginDataEntry<T extends object> extends Omit<(typeof StudioCMSPluginData)['Select']['Type'], 'data'> {
+    data: T;
+}
+/**
+ * Represents a JSON validator function for a specific type.
+ *
+ * @template T - The type that the validator function checks for.
+ * @property jsonFn - A type guard function that determines if the provided data is of type T.
+ */
+export interface JSONValidatorFn<T> {
+    jsonFn: (data: unknown) => data is T;
+}
+/**
+ * Interface representing a validator for an effect schema.
+ *
+ * @typeParam T - The type of the value that the schema validates.
+ *
+ * @property effectSchema - The schema used for validation, which takes a value of type `T` and returns either a `ParseError` or `never`.
+ */
+export interface EffectSchemaValidator<E extends Schema.Struct<any>> {
+    effectSchema: E;
+}
+/**
+ * Interface representing a validator that uses a Zod schema to validate data of type `T`.
+ *
+ * @template T - The type of data to be validated.
+ * @property zodSchema - The Zod schema instance used for validation.
+ */
+export interface ZodValidator<T> {
+    zodSchema: z.ZodSchema<T>;
+}
+/**
+ * Represents the available validator options for a given type `T`.
+ *
+ * This type is a union of supported validator types:
+ * - `JSONValidatorFn<T>`: A function-based JSON validator for type `T`.
+ * - `EffectSchemaValidator<T>`: A validator using the Effect schema for type `T`.
+ * - `ZodValidator<T>`: A validator using the Zod schema for type `T`.
+ *
+ * @template T - The type to be validated.
+ *
+ * @example
+ * ```typescript
+ * // The Interface for a User type
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Example of defining a JSON validator Fn for a User type
+ * const userValidator: ValidatorOptions<User> = {
+ *   jsonFn: (data: unknown): data is User => {
+ *     return (
+ *       typeof data === 'object' &&
+ *       data !== null &&
+ *       'id' in data &&
+ *       'name' in data &&
+ *       'email' in data &&
+ *       typeof (data as any).id === 'number' &&
+ *       typeof (data as any).name === 'string' &&
+ *       typeof (data as any).email === 'string'
+ *     );
+ *   }
+ * };
+ *
+ * // Example of defining an Effect schema validator for a User type
+ * import { Schema } from 'studiocms/effect';
+ *
+ * const userEffectSchema = Schema.Struct({
+ *  id: Schema.Number,
+ *  name: Schema.String,
+ *  email: Schema.String
+ * });
+ *
+ * type UserEffectSchema = (typeof userEffectSchema)['Type'];
+ * type UserEffectSchemaFields = (typeof userEffectSchema)['fields'];
+ *
+ * const userEffectValidator: ValidatorOptions<UserEffectSchema, UserEffectSchemaFields> = {
+ *   effectSchema: userEffectSchema
+ * };
+ *
+ * // Example of defining a Zod validator for a User type
+ * import { z } from 'astro/zod';
+ *
+ * const userZodValidator: ValidatorOptions<User> = {
+ *   zodSchema: z.object({
+ *     id: z.number(),
+ *     name: z.string(),
+ *     email: z.string()
+ *   })
+ * };
+ * ```
+ */
+export type ValidatorOptions<T extends Schema.Struct<any> | object> = T extends Schema.Struct<any> ? EffectSchemaValidator<T> : JSONValidatorFn<T> | ZodValidator<T>;
+export type RecursiveSimplifyMutable<A> = {
+    -readonly [K in keyof A]: A[K] extends object ? RecursiveSimplifyMutable<A[K]> : A[K];
+} extends infer B ? B : never;
+/**
+ * Enum representing the possible responses when selecting plugin data,
+ * indicating whether the existence of the data should cause a failure or not.
+ *
+ * @enum {string}
+ * @property {string} ExistsNoFail - The plugin data exists and should not cause a failure.
+ * @property {string} ExistsShouldFail - The plugin data exists and should cause a failure.
+ */
+export declare enum SelectPluginDataRespondOrFail {
+    ExistsNoFail = "existsNoFail",
+    ExistsShouldFail = "existsShouldFail",
+    NotExistsShouldFail = "notExistsShouldFail"
+}
+/**
+ * Wraps the provided `id` and `data` into a `PluginDataEntry<T>` object and returns it as an Effect.
+ *
+ * @template T - The type of the data to be wrapped.
+ * @param id - The unique identifier for the plugin data entry.
+ * @param data - The data to be associated with the given id.
+ * @returns An Effect that, when executed, yields a `PluginDataEntry<T>` containing the provided id and data.
+ */
+export declare const parsedDataResponse: <T extends object>(id: string, data: T) => Effect.Effect<PluginDataEntry<T>, never, never>;
+/**
+ * Filters out `undefined` and `null` values from an array of entries.
+ *
+ * @typeParam T - The type of the array elements.
+ * @param entries - An array containing elements of type `T` or `undefined`.
+ * @returns A new array containing only the defined (non-`undefined`, non-`null`) entries of type `T`.
+ */
+export declare function noUndefinedEntries<T>(entries: (T | undefined)[]): T[];
+/**
+ * Returns a function that validates a boolean condition and either returns the provided value
+ * cast to type `T` if the condition is true, or throws an error if the condition is false.
+ *
+ * @typeParam T - The expected type of the validated object.
+ * @param data - The value to be validated and potentially returned as type `T`.
+ * @returns A function that takes a boolean indicating validation success.
+ * @throws {Error} If the boolean argument is false, throws an error with the serialized value.
+ *
+ * @example
+ * ```typescript
+ * const validateUser = isJsonValid<User>(userData);
+ * const user = validateUser(isUserValid); // Returns userData as User if valid, otherwise throws.
+ * ```
+ */
+export declare const isJsonValid: <T extends object>(data: unknown) => (isValid: boolean) => T;
+/**
+ * Returns a validator function based on the provided validator options.
+ *
+ * This function supports three types of validators:
+ * - `jsonFn`: A custom JSON validation function.
+ * - `effectSchema`: An Effect schema for validation.
+ * - `zodSchema`: A Zod schema for validation.
+ *
+ * The returned validator function takes unknown data and attempts to validate it
+ * according to the specified validator. If validation succeeds, the data is returned
+ * as type `T`. If validation fails, an error is thrown or returned as an Effect error.
+ *
+ * @typeParam T - The expected type of the validated data.
+ * @param validator - The validator options, which must include one of: `jsonFn`, `effectSchema`, or `zodSchema`.
+ * @returns A function that takes unknown data and returns an Effect that resolves to type `T` if validation succeeds, or fails with an error if validation fails.
+ * @throws Error if none of the expected validator options are provided.
+ */
+export declare const getValidatorFn: <T extends Schema.Struct<Schema.Struct.Fields> | object>(validator: ValidatorOptions<T>) => Effect.Effect<(data: unknown) => Effect.Effect<T, Error, never>, Error, never>;
+/**
+ * Parses and validates plugin data from a raw input, supporting multiple validation strategies.
+ *
+ * This function attempts to parse the provided `rawData`, which can be either a JSON string or an object.
+ * If a validator is provided, it validates the parsed data using one of the supported validation methods:
+ * - JSON function (`jsonFn`)
+ * - Effect schema (`effectSchema`)
+ * - Zod schema (`zodSchema`)
+ *
+ * If no validator is provided, the parsed data is returned as is.
+ * If validation fails or the input format is invalid, an error is yielded.
+ *
+ * @typeParam T - The expected type of the parsed and validated data.
+ * @param rawData - The raw input data, which can be a JSON string or an object.
+ * @param validator - Optional. An object specifying the validation strategy to use.
+ * @returns An `Effect` yielding the parsed and validated data of type `T`, or an error if parsing or validation fails.
+ *
+ * @throws {Error} If the input is neither a string nor an object, or if parsing/validation fails.
+ */
+export declare const parseData: <T extends Schema.Struct<Schema.Struct.Fields> | object>(rawData: unknown, validator?: ValidatorOptions<T> | undefined) => Effect.Effect<T, Error, never>;
+/**
+ * Base options for using plugin data.
+ *
+ * @template T - The type of the data object.
+ * @property [Type] - An optional type definition for the data.
+ * @property [validator] - Optional validator options for the data type.
+ */
+export interface UsePluginDataOptsBase<T extends Schema.Struct<Schema.Struct.Fields> | object> {
+    Type?: T;
+    validator?: ValidatorOptions<T>;
+}
+/**
+ * Options for using plugin data, extending the base options with an entry identifier.
+ *
+ * @template T - The type of the plugin data object.
+ * @extends UsePluginDataOptsBase<T>
+ *
+ * @property entryId - The unique identifier for the entry associated with the plugin data.
+ */
+export interface UsePluginDataOpts<T extends Schema.Struct<Schema.Struct.Fields> | object> extends UsePluginDataOptsBase<T> {
+    entryId: string;
+}
+/**
+ * Represents a partial implementation of the `UsePluginDataOpts` type for a given object type `T`.
+ *
+ * This type is useful when you want to provide only a subset of the properties defined in `UsePluginDataOpts<T>`.
+ *
+ * @typeParam T - The object type for which the plugin data options are defined.
+ */
+export type UserPluginDataOptsImplementation<T extends Schema.Struct<Schema.Struct.Fields> | object> = Partial<UsePluginDataOpts<T>>;

package/dist/lib/pluginUtils.js

@@ -0,0 +1,80 @@
+import { Effect, pipe, Schema } from "@withstudiocms/effect";
+var SelectPluginDataRespondOrFail = /* @__PURE__ */ ((SelectPluginDataRespondOrFail2) => {
+  SelectPluginDataRespondOrFail2["ExistsNoFail"] = "existsNoFail";
+  SelectPluginDataRespondOrFail2["ExistsShouldFail"] = "existsShouldFail";
+  SelectPluginDataRespondOrFail2["NotExistsShouldFail"] = "notExistsShouldFail";
+  return SelectPluginDataRespondOrFail2;
+})(SelectPluginDataRespondOrFail || {});
+const parsedDataResponse = (id, data) => Effect.succeed({
+  id,
+  data
+});
+function noUndefinedEntries(entries) {
+  return entries.filter((entry) => entry !== void 0 && entry !== null);
+}
+const isJsonValid = (data) => (isValid) => {
+  if (isValid) return data;
+  throw new Error("Validation failed for plugin data");
+};
+const getValidatorFn = Effect.fn("studiocms/sdk/effect/pluginUtils/getValidatorFn")(
+  function* (validator) {
+    if ("jsonFn" in validator) {
+      return (data) => Effect.try({
+        try: () => pipe(validator.jsonFn(data), isJsonValid(data)),
+        catch: (error) => new Error(`JSON validation failed: ${error.message}`)
+      });
+    }
+    if ("effectSchema" in validator) {
+      return (data) => Schema.decodeUnknown(validator.effectSchema)(data).pipe(
+        Effect.mapError(
+          (error) => new Error(`Schema validation failed: ${error.message}`)
+        )
+      );
+    }
+    if ("zodSchema" in validator) {
+      return (data) => Effect.try({
+        try: () => {
+          const result = validator.zodSchema.safeParse(data);
+          if (result.success) {
+            return result.data;
+          }
+          throw new Error(`Zod validation failed: ${result.error.message}`, {
+            cause: result.error.cause
+          });
+        },
+        catch: (error) => new Error(error.message, { cause: error.cause })
+      });
+    }
+    return yield* Effect.fail(
+      new Error(
+        "Invalid validator options provided, expected one of: jsonFn, effectSchema, or zodSchema"
+      )
+    );
+  }
+);
+const parseData = Effect.fn("studiocms/sdk/effect/pluginUtils/parseData")(function* (rawData, validator) {
+  let parsedInput;
+  if (typeof rawData === "string") {
+    parsedInput = yield* Effect.try({
+      try: () => JSON.parse(rawData),
+      catch: (error) => new Error(`JSON parsing failed: ${error}`)
+    });
+  } else if (rawData !== null && typeof rawData === "object") {
+    parsedInput = rawData;
+  } else {
+    return yield* Effect.fail(new Error(`Invalid plugin data format: ${typeof rawData}`));
+  }
+  if (!validator || validator === void 0) {
+    return parsedInput;
+  }
+  const validatorFn = yield* getValidatorFn(validator);
+  return yield* validatorFn(parsedInput);
+});
+export {
+  SelectPluginDataRespondOrFail,
+  getValidatorFn,
+  isJsonValid,
+  noUndefinedEntries,
+  parseData,
+  parsedDataResponse
+};