@withstudiocms/sdk 0.0.0-beta.0 → 0.1.0

package/dist/modules/index.js

@@ -0,0 +1,37 @@
+import AUTH from "./auth/index.js";
+import CLEAR from "./clear/index.js";
+import CONFIG from "./config/index.js";
+import DELETE from "./delete/index.js";
+import diffTracking from "./diffTracking/index.js";
+import GET from "./get/index.js";
+import INIT from "./init/index.js";
+import MIDDLEWARES from "./middleware/index.js";
+import notificationSettings from "./notificationSettings/index.js";
+import PLUGINS from "./plugins/index.js";
+import POST from "./post/index.js";
+import resetTokenBucket from "./resetTokenBucket/index.js";
+import REST_API from "./rest_api/index.js";
+import UPDATE from "./update/index.js";
+import UTIL from "./util/index.js";
+const SDKModules = {
+  AUTH,
+  CLEAR,
+  CONFIG,
+  DELETE,
+  diffTracking,
+  GET,
+  INIT,
+  MIDDLEWARES,
+  notificationSettings,
+  PLUGINS,
+  POST,
+  resetTokenBucket,
+  REST_API,
+  UPDATE,
+  UTIL
+};
+var modules_default = SDKModules;
+export {
+  SDKModules,
+  modules_default as default
+};

package/dist/modules/init/index.d.ts

@@ -0,0 +1,60 @@
+import { Effect } from '@withstudiocms/effect';
+/**
+ * Initializes and exposes core StudioCMS SDK initialization utilities as an Effect.
+ *
+ * This module is an Effect.gen that awaits the SDK configuration and authentication modules
+ * (SDKConfigModule and SDKAuthModule) and returns a small initialization surface for
+ * higher-level SDK setup tasks.
+ *
+ * The returned object has two primary members:
+ * - siteConfig: a function that initializes the StudioCMS SiteConfig table with the provided configuration.
+ *   Use this to seed or update the persisted site configuration used by the SDK.
+ * - ghostUser: a function that returns the system "ghost" user record. The ghost user is a default
+ *   actor used for system-level actions and to replace deleted users when needed.
+ *
+ * Remarks:
+ * - This Effect does not itself perform site or user initialization on import; it resolves to an object
+ *   exposing operations that perform those tasks when invoked.
+ * - If SDKConfigModule or SDKAuthModule fail to initialize, this Effect will fail accordingly.
+ *
+ *
+ * Example:
+ * ```ts
+ * // inside an Effect.gen context
+ * const init = yield* SDKInitModule;
+ * // initialize site configuration
+ * yield* init.siteConfig(mySiteConfig);
+ * // fetch the ghost user
+ * const ghost = yield* init.ghostUser();
+ * ```
+ */
+export declare const SDKInitModule: Effect.Effect<{
+    /**
+     * Initializes the StudioCMS SiteConfig table with the provided configuration.
+     *
+     * @param config - The configuration to insert into the SiteConfig table.
+     * @returns A promise that resolves to the inserted site configuration.
+     */
+    siteConfig: (data: import("../../types.js").ConfigFinal<import("../../types.js").StudioCMSSiteConfig>) => Effect.Effect<import("../../types.js").DynamicConfigEntry<import("../../types.js").StudioCMSSiteConfig>, import("@withstudiocms/kysely/client").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+    /**
+     * Initializes the StudioCMS Ghost User.
+     *
+     * The ghost user is a default user that is used to perform actions on behalf of the system as well as to replace deleted users.
+     *
+     * @returns A promise that resolves to the ghost user record.
+     */
+    ghostUser: () => Effect.Effect<{
+        readonly id: string;
+        readonly url?: string | null | undefined;
+        readonly name: string;
+        readonly email?: string | null | undefined;
+        readonly avatar?: string | null | undefined;
+        readonly username: string;
+        readonly password?: string | null | undefined;
+        readonly updatedAt: Date;
+        readonly createdAt: Date;
+        readonly emailVerified: boolean;
+        readonly notifications?: string | null | undefined;
+    }, import("@withstudiocms/kysely/client").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+}, import("effect/ConfigError").ConfigError, import("../../context.js").DBClientLive | import("../../context.js").SDKDefaults | import("../../context.js").StorageManagerResolver | import("../../cache.js").CacheService | import("@withstudiocms/effect").Deepmerge>;
+export default SDKInitModule;

package/dist/modules/init/index.js

@@ -0,0 +1,38 @@
+import { Effect } from "@withstudiocms/effect";
+import SDKAuthModule from "../auth/index.js";
+import SDKConfigModule from "../config/index.js";
+const SDKInitModule = Effect.gen(function* () {
+  const [
+    {
+      siteConfig: { init: initSiteConfig }
+    },
+    {
+      user: {
+        ghost: { get: initGhostUser }
+      }
+    }
+  ] = yield* Effect.all([SDKConfigModule, SDKAuthModule]);
+  const INIT = {
+    /**
+     * Initializes the StudioCMS SiteConfig table with the provided configuration.
+     *
+     * @param config - The configuration to insert into the SiteConfig table.
+     * @returns A promise that resolves to the inserted site configuration.
+     */
+    siteConfig: initSiteConfig,
+    /**
+     * Initializes the StudioCMS Ghost User.
+     *
+     * The ghost user is a default user that is used to perform actions on behalf of the system as well as to replace deleted users.
+     *
+     * @returns A promise that resolves to the ghost user record.
+     */
+    ghostUser: initGhostUser
+  };
+  return INIT;
+});
+var init_default = SDKInitModule;
+export {
+  SDKInitModule,
+  init_default as default
+};

package/dist/modules/middleware/index.d.ts

@@ -0,0 +1,56 @@
+import { Effect } from '@withstudiocms/effect';
+import CacheService from '../../cache.js';
+/**
+ * SDKMiddlewareModule
+ *
+ * Initializes and exposes middleware-related effects for the SDK.
+ *
+ * This module composes several underlying services (SDKGetModule, SDKPluginsModule,
+ * CacheService) to produce a memoized effect that verifies and populates middleware
+ * caches used across the application. The verification process updates:
+ * - pages (with a forced refresh)
+ * - folder tree
+ * - page-folder tree
+ * - folder list
+ * - site configuration
+ * - plugin data cache
+ *
+ * The verification effect logs the start and end of the operation and measures the
+ * duration for performance monitoring.
+ *
+ * The primary exported value is:
+ * - verifyCache: a memoized Effect that runs the full cache verification pipeline.
+ *
+ * Key behaviors and guarantees
+ * - Memoized: verifyCache is wrapped with a memoization layer (tags: middleware)
+ *   and configured with a TTL of 30 minutes to avoid redundant executions.
+ * - Side effects: the effect performs network/cache updates and logging.
+ * - Concurrency: repeated invocations while a verification is in progress will
+ *   leverage the memoization to avoid duplicating work for the same cache key.
+ * - Failure semantics: failures from any underlying update (pages, folder tree,
+ *   plugin initialization, etc.) will propagate through the effect; callers should
+ *   handle or surface errors as appropriate.
+ * - Cancellation: the effect follows the cancellation semantics of the underlying
+ *   Effect runtime (i.e., it may be cancelable depending on the implementation of
+ *   the composed effects).
+ *
+ * Usage:
+ * - Run or schedule verifyCache to ensure middleware caches are initialized and kept
+ *   fresh. Because it is memoized with a TTL, it is inexpensive to call repeatedly
+ *   from different parts of the system.
+ *
+ * @remarks
+ * - This module has implicit dependencies on SDKGetModule, SDKPluginsModule and
+ *   CacheService; it should be provided/loaded within the same Effect environment.
+ *
+ * @returns An object containing:
+ *   - verifyCache: a memoized Effect that verifies and initializes middleware caches.
+ *
+ * @example
+ * // Example invocation (pseudocode)
+ * // yield* Effect.flatMap(SDKMiddlewareModule, ({ verifyCache }) => verifyCache)
+ */
+export declare const SDKMiddlewareModule: Effect.Effect<{
+    verifyCache: () => Effect.Effect<void, import("effect/Cause").UnknownException | import("effect/ParseResult").ParseError | import("@withstudiocms/kysely/client").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").QueryParseError | import("@withstudiocms/kysely/core/errors").QueryError | import("@withstudiocms/kysely/core/errors").NotFoundError | import("../util/folderTree.js").FolderTreeError | import("../util/collectors.js").CollectorError | import("../get/index.js").PaginateError, never>;
+}, never, import("../../context.js").DBClientLive | import("../../context.js").SDKDefaults | import("../../context.js").StorageManagerResolver | CacheService | import("@withstudiocms/effect").Deepmerge>;
+export default SDKMiddlewareModule;

package/dist/modules/middleware/index.js

@@ -0,0 +1,50 @@
+import { Duration, Effect } from "@withstudiocms/effect";
+import CacheService from "../../cache.js";
+import { cacheKeyGetters, cacheTags } from "../../consts.js";
+import SDKGetModule from "../get/index.js";
+import SDKPluginsModule from "../plugins/index.js";
+const SDKMiddlewareModule = Effect.gen(function* () {
+  const [
+    {
+      pages: updatePages,
+      folderTree: updateFolderTree,
+      pageFolderTree: updatePageFolderTree,
+      folderList: updateFolderList,
+      siteConfig: updateSiteConfig
+    },
+    { initPluginDataCache },
+    { memoize }
+  ] = yield* Effect.all([SDKGetModule, SDKPluginsModule, CacheService]);
+  const _verifyCacheEffect = Effect.log("Verifying middleware caches...").pipe(
+    Effect.map(() => Date.now()),
+    Effect.flatMap(
+      (startTime) => Effect.all({
+        pages: updatePages(true),
+        folderTree: updateFolderTree(),
+        pageFolderTree: updatePageFolderTree(),
+        folderList: updateFolderList(),
+        siteConfig: updateSiteConfig(),
+        pluginData: initPluginDataCache(),
+        startTime: Effect.succeed(startTime)
+      })
+    ),
+    Effect.flatMap(({ startTime }) => Effect.succeed({ startTime, endTime: Date.now() })),
+    Effect.flatMap(
+      ({ startTime, endTime }) => Effect.log(`Middleware caches verified in ${endTime - startTime}ms.`)
+    )
+  );
+  const verifyCache = Effect.fn(
+    () => memoize(cacheKeyGetters.middleware(), _verifyCacheEffect, {
+      tags: cacheTags.middleware,
+      ttl: Duration.minutes(30)
+    }).pipe(Effect.tap(() => Effect.logDebug("Completed middleware cache verification.")))
+  );
+  return {
+    verifyCache
+  };
+});
+var middleware_default = SDKMiddlewareModule;
+export {
+  SDKMiddlewareModule,
+  middleware_default as default
+};

package/dist/modules/notificationSettings/index.d.ts

@@ -0,0 +1,57 @@
+import { Effect } from '@withstudiocms/effect';
+import { SDKDefaults } from '../../context.js';
+import type { StudioCMSNotificationSettings } from '../../types.js';
+/**
+ * SDKNotificationSettingsModule
+ *
+ * Effect-based module that exposes site-scoped notification settings operations.
+ *
+ * This module depends on SDKConfigModule and SDKDefaults to read the current
+ * notification configuration and to obtain default settings when none exist.
+ *
+ * The yielded object has the shape:
+ * {
+ *   site: {
+ *     get: Effect<...>,    // retrieves the site notification settings, initializing with defaults if absent
+ *     update: Effect<...>  // updates the site notification settings (accepts settings without `_config_version`)
+ *   }
+ * }
+ *
+ * Behavior:
+ * - get: Reads the current `notificationConfig`. If a configuration is present, it is returned.
+ *   If not present, the configuration is initialized using `NotificationSettingsDefaults` and the
+ *   initialized value is returned.
+ *
+ * - update: Persists new site notification settings. The provided `settings` argument should omit
+ *   the internal `_config_version` field (i.e. `Omit<StudioCMSNotificationSettings, '_config_version'>`).
+ *
+ * Remarks:
+ * - The module is created inside an Effect.gen generator and therefore must be run within the
+ *   surrounding Effect runtime to obtain the returned operations.
+ * - All operations are effectful and should be composed/run via the project's Effect primitives.
+ *
+ * Example:
+ * ```ts
+ * const module = yield* Effect.runPromise(SDKNotificationSettingsModule);
+ * const current = yield* Effect.runPromise(module.site.get());
+ * yield* Effect.runPromise(module.site.update({ ...new_settings }));
+ * ```
+ *
+ * @returns An Effect that yields an object with a `site` namespace containing `get` and `update` operations for site notification settings.
+ */
+export declare const SDKNotificationSettingsModule: Effect.Effect<{
+    /**
+     * Site-specific notification settings.
+     */
+    site: {
+        /**
+         * Retrieves the site-wide notification settings.
+         */
+        get: () => Effect.Effect<import("../../types.js").DynamicConfigEntry<StudioCMSNotificationSettings>, import("@withstudiocms/kysely/client").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Updates the site-wide notification settings.
+         */
+        update: (settings: Omit<StudioCMSNotificationSettings, "_config_version">) => Effect.Effect<import("../../types.js").DynamicConfigEntry<StudioCMSNotificationSettings>, import("@withstudiocms/kysely/client").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+    };
+}, never, import("../../context.js").DBClientLive | SDKDefaults | import("../../context.js").StorageManagerResolver | import("../../cache.js").CacheService | import("@withstudiocms/effect").Deepmerge>;
+export default SDKNotificationSettingsModule;

package/dist/modules/notificationSettings/index.js

@@ -0,0 +1,39 @@
+import { Effect } from "@withstudiocms/effect";
+import { SDKDefaults } from "../../context.js";
+import { SDKConfigModule } from "../config/index.js";
+const SDKNotificationSettingsModule = Effect.gen(function* () {
+  const [{ notificationConfig }, { NotificationSettingsDefaults }] = yield* Effect.all([
+    SDKConfigModule,
+    SDKDefaults
+  ]);
+  const _getNotificationConfig = Effect.fn(
+    () => notificationConfig.get().pipe(
+      Effect.flatMap(
+        (data) => data ? Effect.succeed(data) : notificationConfig.init(NotificationSettingsDefaults)
+      )
+    )
+  );
+  const _updateNotificationConfig = Effect.fn(
+    (settings) => notificationConfig.update(settings)
+  );
+  return {
+    /**
+     * Site-specific notification settings.
+     */
+    site: {
+      /**
+       * Retrieves the site-wide notification settings.
+       */
+      get: _getNotificationConfig,
+      /**
+       * Updates the site-wide notification settings.
+       */
+      update: _updateNotificationConfig
+    }
+  };
+});
+var notificationSettings_default = SDKNotificationSettingsModule;
+export {
+  SDKNotificationSettingsModule,
+  notificationSettings_default as default
+};

package/dist/modules/plugins/index.d.ts

@@ -0,0 +1,167 @@
+import { Effect, Schema } from '@withstudiocms/effect';
+import CacheService from '../../cache.js';
+import { DBClientLive } from '../../context.js';
+import { StudioCMSSDKError } from '../../errors.js';
+import { type PluginDataEntry, type RecursiveSimplifyMutable, type UsePluginDataOpts, type UsePluginDataOptsBase } from '../../lib/pluginUtils.js';
+/**
+ * SDKPluginsModule
+ *
+ * Effect-based module that provides a complete set of utilities for managing plugin-scoped
+ * data entries persisted in the `StudioCMSPluginData` table and cached in an application cache.
+ * The module is implemented as an Effect.gen and depends on a database client and a cache
+ * service. It combines typed codecs, validation, database operations, and caching/memoization
+ * to provide a safe and ergonomic API for plugin authors.
+ *
+ * Key responsibilities
+ * - Database access:
+ *   - Batched reads of plugin data for cache initialization.
+ *   - Select, insert and update operations for single plugin data entries.
+ *   - All DB operations are wrapped with codecs to validate/encode inputs and decode results.
+ *
+ * - Caching:
+ *   - Per-entry memoization via a cache key derived from the plugin+entry id.
+ *   - Batch cache population via `initPluginDataCache`.
+ *   - Cache invalidation support via `clearPluginDataCache` (invalidates plugin tags).
+ *   - Cache entries include a shared timestamp for a single initialization run.
+ *
+ * - Validation and parsing:
+ *   - Data payloads are parsed and optionally validated with provided validator options
+ *     before being inserted/updated or returned to callers.
+ *   - Helpers wrap parsed results into a consistent `PluginDataEntry<T>` response.
+ *
+ * Public API (returned object)
+ * - usePluginData(pluginId, opts?)
+ *   Overloaded function:
+ *   1) usePluginData(pluginId, opts?: UsePluginDataOptsBase<T>)
+ *      - Returns:
+ *        - getEntries(filter?) => Effect<PluginDataEntry<R>[], Error, never>
+ *          Retrieves all entries for a pluginId, optionally applying an in-memory filter
+ *          after validation and parsing.
+ *        - getEntry(id) => builder object (generatedId, select, insert, update)
+ *          Returns a per-entry builder for convenience when working with many entries.
+ *
+ *   2) usePluginData(pluginId, opts?: UsePluginDataOpts<T>)  (when entryId provided in opts)
+ *      - Returns a per-entry API:
+ *        - generatedId(): Effect<string, never, never> -- returns `${pluginId}-${entryId}`.
+ *        - select(): Effect<PluginDataEntry<R> | undefined, Error, never> -- reads, validates and returns parsed data.
+ *        - insert(data: R): Effect<PluginDataEntry<R>, Error, never> -- validates and inserts a new entry.
+ *        - update(data: R): Effect<PluginDataEntry<R>, Error, never> -- validates and updates an existing entry.
+ *
+ *   - Generic behavior:
+ *     - `T` is the schema or object type used for validation.
+ *     - `R` is the resolved/public type used in returned `PluginDataEntry<R>`.
+ *     - All operations return Effects and preserve typed validation semantics.
+ *
+ * - initPluginDataCache(BATCH_SIZE)
+ *   - Walks the `StudioCMSPluginData` table in batches and populates the cache with
+ *     all existing entries. Uses a single timestamp for each initialization run to
+ *     mark `lastCacheUpdate` consistently across entries.
+ *   - Batch size defaults and safety: accepts a batch size, coerces non-positive values
+ *     to a sane default (e.g. 100).
+ *
+ * - clearPluginDataCache()
+ *   - Invalidates cache entries for plugin data using configured cache tags.
+ *
+ * - InferType<S extends Schema.Struct<any>>
+ *   - Utility class for inferring and re-exporting schema-derived types (e.g. the
+ *     simplified/recursive `Insert` type) to help consumers derive correct generics
+ *     for `usePluginData`.
+ *
+ * Error semantics
+ * - DB/validation errors are surfaced as Effect failures (Error).
+ * - Insert/update operations perform existence checks and will fail on duplicate inserts
+ *   or updates to non-existent entries (controlled internally via SelectPluginDataRespondOrFail).
+ *
+ * Implementation notes (high-level)
+ * - DB interactions are performed via a `withCodec` wrapper that enforces input/output
+ *   shapes at the codec boundary.
+ * - Per-entry caching is implemented using `memoize(cacheKey(id), dbCall, cacheOpts)`.
+ * - Initialization uses a batched DB query and writes entries into the cache via `set`.
+ * - Processing path for DB entries:
+ *   1) Read raw DB entry (JSON string payload).
+ *   2) parseData -> validate (if validator provided).
+ *   3) Wrap into consistent `PluginDataEntry<T>` response.
+ *
+ * Example usage
+ * @example
+ * // Get all entries for plugin "com.example"
+ * const sdk = yield* SDKPluginsModule;
+ * const getAll = sdk.usePluginData('com.example');
+ * const entries = yield* getAll.getEntries();
+ *
+ * // Work with a specific entry
+ * const entryApi = sdk.usePluginData('com.example', { entryId: 'myEntry', validator: mySchema });
+ * const existing = yield* entryApi.select();
+ * const inserted = yield* entryApi.insert({ foo: 'bar' });
+ *
+ * Thread-safety & concurrency
+ * - Cache and DB operations are effectful and composable; callers should coordinate
+ *   concurrent modifications as needed (e.g. optimistic strategies) depending on application needs.
+ *
+ * Notes for contributors
+ * - Keep codecs and validators up-to-date with DB schema.
+ * - Ensure cache tag names and key generation remain stable to avoid stale cache bugs.
+ */
+export declare const SDKPluginsModule: Effect.Effect<{
+    /**
+     * Provides a set of effectful operations for managing plugin data entries by plugin ID and optional entry ID.
+     *
+     * When an `entryId` is provided, returns an object with methods to:
+     * - Generate a unique plugin data entry ID.
+     * - Insert new plugin data after validation and duplicate checks.
+     * - Select and validate existing plugin data by ID.
+     * - Update existing plugin data after validation.
+     *
+     * When no `entryId` is provided, returns an object with a method to retrieve all entries for the given plugin.
+     *
+     * @param pluginId - The unique identifier for the plugin.
+     * @param entryId - (Optional) The unique identifier for the plugin data entry.
+     * @returns An object with effectful methods for plugin data management, varying by presence of `entryId`.
+     */
+    usePluginData: {
+        <T extends Schema.Struct<Schema.Struct.Fields> | object, R extends object = T extends Schema.Struct<any> ? RecursiveSimplifyMutable<T["Type"]> : T>(pluginId: string, opts?: UsePluginDataOptsBase<T>): {
+            getEntries: (filter?: (data: PluginDataEntry<R>[]) => PluginDataEntry<R>[]) => Effect.Effect<PluginDataEntry<R>[], StudioCMSSDKError, never>;
+            getEntry: (id: string) => {
+                generatedId: () => Effect.Effect<string, never, never>;
+                select: () => Effect.Effect<PluginDataEntry<R> | undefined, StudioCMSSDKError, never>;
+                insert: (data: R) => Effect.Effect<PluginDataEntry<R>, StudioCMSSDKError, never>;
+                update: (data: R) => Effect.Effect<PluginDataEntry<R>, StudioCMSSDKError, never>;
+            };
+        };
+        <T extends Schema.Struct<Schema.Struct.Fields> | object, R extends object = T extends Schema.Struct<any> ? RecursiveSimplifyMutable<T["Type"]> : T>(pluginId: string, opts?: UsePluginDataOpts<T>): {
+            generatedId: () => Effect.Effect<string, never, never>;
+            select: () => Effect.Effect<PluginDataEntry<R> | undefined, StudioCMSSDKError, never>;
+            insert: (data: R) => Effect.Effect<PluginDataEntry<R>, StudioCMSSDKError, never>;
+            update: (data: R) => Effect.Effect<PluginDataEntry<R>, StudioCMSSDKError, never>;
+        };
+    };
+    /**
+     * Initializes the plugin data cache by fetching all existing entries from the database
+     * and populating the in-memory cache with these entries.
+     */
+    initPluginDataCache: (BATCH_SIZE?: number | undefined) => Effect.Effect<void, import("@withstudiocms/kysely/client").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+    /**
+     * Clears the plugin data cache, removing all cached entries.
+     *
+     * @returns An Effect that resolves to `void` on success or an `Error` on failure.
+     */
+    clearPluginDataCache: () => Effect.Effect<void, never, never>;
+    /**
+     * Utility class to infer types from a given Schema.
+     *
+     * @typeParam S - The schema type extending `Schema.Struct<any>`.
+     *
+     * @property _Schema - The schema instance used for type inference.
+     * @property usePluginData - The inferred type from the schema, used for plugin data.
+     * @property Insert - A recursively simplified, mutable version of the schema's type.
+     *
+     */
+    InferType: {
+        new <S extends Schema.Struct<any>, R = RecursiveSimplifyMutable<S["Type"]>>(schema: S): {
+            readonly _Schema: S;
+            readonly $UsePluginData: S;
+            readonly $Insert: R;
+        };
+    };
+}, never, DBClientLive | CacheService>;
+export default SDKPluginsModule;