@withstudiocms/sdk 0.0.0-beta.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present StudioCMS - withstudiocms (https://github.com/withstudiocms)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @withstudiocms/sdk
+
+A comprehensive Software Development Kit for StudioCMS, providing a unified API for interacting with the CMS core functionality. Built with TypeScript and Effect-ts for type-safety and functional programming patterns, with Kysely DB (`@withstudiocms/kysely`) for dynamic database storage.
+
+**Note:** This is an Internal to StudioCMS package. Not intended to be used directly.
+
+## Features
+- **Authentication Module** - User authentication and session management
+- **Configuration Management** - Type-safe configuration handling with validation
+- **Database Operations** - CRUD operations with Effect-ts error handling
+- **Plugin System** - Utilities for plugin development and integration
+- **Caching Layer** - Built-in caching with query memoization and invalidation
+- **Middleware Utilities** - Request handling and middleware composition
+- **Diff Tracking** - Track changes and modifications
+- **REST API Helpers** - Utilities for building REST endpoints
+- **Notification Settings** - User notification preference management
+- **Token Bucket** - Rate limiting and token management
+
+## License
+
+[MIT Licensed](./LICENSE)

package/dist/cache.d.ts

@@ -0,0 +1,109 @@
+import { Duration, Effect } from '@withstudiocms/effect';
+import { CacheStores } from './context.js';
+/**
+ * Represents a cache entry with a value, expiration time, and associated tags.
+ *
+ * @template A - The type of the cached value.
+ */
+export interface CacheEntry<A> {
+    value: A;
+    expiresAt: number;
+    lastUpdatedAt: number;
+    tags: Set<string>;
+}
+/**
+ * Represents the status of a cache entry, including expiration and tags.
+ */
+export interface CacheEntryStatus {
+    expiresAt: Date;
+    lastUpdatedAt: Date;
+    tags: Set<string>;
+}
+/**
+ * Error indicating that a requested cache entry was not found.
+ */
+export declare class CacheMissError {
+    readonly _tag = "CacheMissError";
+}
+/**
+ * Helper function to return a non-null value or fail with CacheMissError.
+ *
+ * @template A - The type of the value.
+ * @param value - The value to check.
+ * @returns An Effect that yields the value or fails with CacheMissError.
+ */
+export declare const returnNonNull: <A>(value: A | null) => Effect.Effect<A, CacheMissError>;
+declare const CacheService_base: Effect.Service.Class<CacheService, "@withstudiocms/sdk/cache/CacheService", {
+    readonly effect: Effect.Effect<{
+        get: <A>(key: string) => Effect.Effect<A | null, never, never>;
+        set: <A>(key: string, value: A, options?: {
+            ttl?: Duration.Duration;
+            tags?: string[];
+        }) => Effect.Effect<void, never, never>;
+        delete: (key: string) => Effect.Effect<void, never, never>;
+        invalidateTags: (tags: string[]) => Effect.Effect<void, never, never>;
+        clear: () => Effect.Effect<void, never, never>;
+        memoize: <A, E, R>(key: string, effect: Effect.Effect<A, E, R>, options?: {
+            ttl?: Duration.Duration;
+            tags?: string[];
+        }) => Effect.Effect<A, E, R>;
+        getCacheStatus: (id: string) => Effect.Effect<{
+            expiresAt: Date;
+            lastUpdatedAt: Date;
+            tags: Set<string>;
+        } | null, never, never>;
+    }, never, CacheStores>;
+}>;
+/**
+ * In-memory caching service implemented as an Effect.Service.
+ *
+ * Provides a small, memory-resident key/value cache with optional per-entry TTL
+ * and tag-based invalidation. Designed to be used from Effects; each operation
+ * returns an Effect that performs the requested action.
+ *
+ * @remarks
+ * - Storage: entries are stored in a Map keyed by string. Each entry contains:
+ *   - value: the cached value (generic)
+ *   - expiresAt: absolute expiration time in milliseconds since epoch
+ *   - tags: a Set of associated tag strings
+ * - Tag index: a separate Map from tag -> Set<key> is maintained to support
+ *   fast invalidation of all entries associated with a given tag.
+ * - Expiration behavior: entries are checked for expiration lazily. An entry
+ *   that has expired will be removed when it is accessed (via get) or when
+ *   explicit invalidation/delete/clear is performed. There is no background
+ *   eviction thread.
+ * - Default TTL: when setting an entry without an explicit ttl option, the
+ *   service uses Duration.minutes(5) as the default time-to-live.
+ * - Concurrency / process model: this is an in-memory, single-process cache.
+ *   It is not persisted and is not safe for cross-process sharing.
+ *
+ * Public API (high-level):
+ * - get<A>(key: string): Effect<..., A | null>
+ *   Retrieve the value for a key. Returns null if the key is missing or expired.
+ *
+ * - set<A>(key: string, value: A, options?: { ttl?: Duration, tags?: string[] }): Effect<..., void>
+ *   Store a value with an optional TTL and optional tags. Tags are used for
+ *   later invalidation. Existing tag->key index entries are updated.
+ *
+ * - delete(key: string): Effect<..., void>
+ *   Remove a single key and remove its references from the tag index.
+ *
+ * - invalidateTags(tags: string[]): Effect<..., void>
+ *   Invalidate (delete) all keys associated with any of the provided tags and
+ *   remove those tags from the tag index.
+ *
+ * - clear(): Effect<..., void>
+ *   Remove all keys and clear the tag index.
+ *
+ * @example
+ * // Pseudocode (Effect-aware)
+ * const cache = yield* CacheService; // obtain CacheService from environment
+ * yield* cache.set('user:1', userObj, { ttl: Duration.minutes(10), tags: ['users', 'recent'] });
+ * const user = yield* cache.get<User>('user:1'); // returns userObj | null
+ * yield* cache.invalidateTags(['users']); // removes all entries tagged 'users'
+ *
+ * @public
+ */
+export declare class CacheService extends CacheService_base {
+}
+export default CacheService;

package/dist/cache.js

@@ -0,0 +1,94 @@
+import { Clock, Duration, Effect } from "@withstudiocms/effect";
+import { CacheStores } from "./context.js";
+class CacheMissError {
+  _tag = "CacheMissError";
+}
+const returnNonNull = (value) => value !== null ? Effect.succeed(value) : Effect.fail(new CacheMissError());
+class CacheService extends Effect.Service()(
+  "@withstudiocms/sdk/cache/CacheService",
+  {
+    effect: Effect.gen(function* () {
+      const { store, tagIndex } = yield* CacheStores;
+      const get = (key) => Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        const entry = store.get(key);
+        if (!entry) return null;
+        if (entry.expiresAt < now) {
+          store.delete(key);
+          return null;
+        }
+        return entry.value;
+      });
+      const set = (key, value, options) => Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        const ttl = options?.ttl ?? Duration.minutes(5);
+        const tags = new Set(options?.tags ?? []);
+        const expiresAt = now + Duration.toMillis(ttl);
+        store.set(key, { value, expiresAt, tags, lastUpdatedAt: now });
+        for (const tag of tags) {
+          if (!tagIndex.has(tag)) {
+            tagIndex.set(tag, /* @__PURE__ */ new Set());
+          }
+          tagIndex.get(tag)?.add(key);
+        }
+      });
+      const deleteKey = (key) => Effect.sync(() => {
+        const entry = store.get(key);
+        if (entry) {
+          for (const tag of entry.tags) {
+            tagIndex.get(tag)?.delete(key);
+          }
+        }
+        store.delete(key);
+      });
+      const invalidateTags = (tags) => Effect.sync(() => {
+        for (const tag of tags) {
+          const keys = tagIndex.get(tag);
+          if (keys) {
+            for (const key of keys) {
+              store.delete(key);
+            }
+            tagIndex.delete(tag);
+          }
+        }
+      });
+      const clear = () => Effect.sync(() => {
+        store.clear();
+        tagIndex.clear();
+      });
+      const memoize = (key, effect, options) => get(key).pipe(
+        Effect.flatMap(returnNonNull),
+        Effect.catchTag(
+          "CacheMissError",
+          () => effect.pipe(Effect.tap((result) => set(key, result, options)))
+        )
+      );
+      const getCacheStatus = Effect.fn(
+        (id) => Effect.gen(function* () {
+          const now = yield* Clock.currentTimeMillis;
+          const entry = store.get(id);
+          if (!entry || entry.expiresAt < now) {
+            if (entry && entry.expiresAt < now) {
+              store.delete(id);
+            }
+            return null;
+          }
+          return {
+            expiresAt: new Date(entry.expiresAt),
+            lastUpdatedAt: new Date(entry.lastUpdatedAt),
+            tags: entry.tags
+          };
+        })
+      );
+      return { get, set, delete: deleteKey, invalidateTags, clear, memoize, getCacheStatus };
+    })
+  }
+) {
+}
+var cache_default = CacheService;
+export {
+  CacheMissError,
+  CacheService,
+  cache_default as default,
+  returnNonNull
+};

package/dist/consts.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cache tags used throughout the SDK.
+ */
+export declare const cacheTags: {
+    dynamicConfig: string[];
+    npmPackage: string[];
+    plugins: string[];
+    folder: string[];
+    folderTree: string[];
+    folderList: string[];
+    pages: string[];
+    pageFolderTree: string[];
+    middleware: string[];
+    taxonomy: string[];
+    tags: string[];
+    categories: string[];
+};
+/**
+ * Functions to generate cache keys for various SDK operations.
+ */
+export declare const cacheKeyGetters: {
+    dynamicConfig: (id: string) => string;
+    npmPackage: (name: string, version: string) => string;
+    plugins: (name: string) => string;
+    folder: (folderId: string) => string;
+    folderTree: () => string;
+    folderList: () => string;
+    page: (pageId: string) => string;
+    pageFolderTree: () => string;
+    middleware: () => string;
+    tags: () => string;
+    categories: () => string;
+    categoryById: (categoryId: number) => string;
+    categoryBySlug: (slug: string) => string;
+    tagById: (tagId: number) => string;
+    tagBySlug: (slug: string) => string;
+};

package/dist/consts.js

@@ -0,0 +1,35 @@
+const cacheTags = {
+  dynamicConfig: ["dynamic-config"],
+  npmPackage: ["npm-package"],
+  plugins: ["plugins"],
+  folder: ["folder"],
+  folderTree: ["folder-tree"],
+  folderList: ["folder-list"],
+  pages: ["pages"],
+  pageFolderTree: ["page-folder-tree"],
+  middleware: ["middleware"],
+  taxonomy: ["taxonomy"],
+  tags: ["tags"],
+  categories: ["categories"]
+};
+const cacheKeyGetters = {
+  dynamicConfig: (id) => `dynamic-config:${id}`,
+  npmPackage: (name, version) => `npm-package:${name.replace("/", "-")}:${version}`,
+  plugins: (name) => `plugins:${name}`,
+  folder: (folderId) => `folder:${folderId}`,
+  folderTree: () => "folder-tree",
+  folderList: () => "folder-list",
+  page: (pageId) => `page:${pageId}`,
+  pageFolderTree: () => "page-folder-tree",
+  middleware: () => "middleware",
+  tags: () => "tags",
+  categories: () => "categories",
+  categoryById: (categoryId) => `category:${categoryId}`,
+  categoryBySlug: (slug) => `category-slug:${slug}`,
+  tagById: (tagId) => `tag:${tagId}`,
+  tagBySlug: (slug) => `tag-slug:${slug}`
+};
+export {
+  cacheKeyGetters,
+  cacheTags
+};

package/dist/context.d.ts

@@ -0,0 +1,208 @@
+import { Context, Layer } from '@withstudiocms/effect';
+import type { DBClientInterface } from '@withstudiocms/kysely/client';
+import type { CacheEntry } from './cache.js';
+import type { StudioCMSDatabaseSchema } from './tables.js';
+declare const DBClientLive_base: Context.TagClass<DBClientLive, "@withstudiocms/sdk/context/DBClientLive", DBClientInterface<{
+    readonly StudioCMSUsersTable: {
+        readonly id: string;
+        readonly name: string;
+        readonly username: string;
+        readonly updatedAt: import("kysely").ColumnType<string, string, string>;
+        readonly createdAt: import("kysely").ColumnType<string, string | undefined, undefined>;
+        readonly emailVerified: number;
+        readonly url?: string | null | undefined;
+        readonly email?: string | null | undefined;
+        readonly avatar?: string | null | undefined;
+        readonly password?: string | null | undefined;
+        readonly notifications?: string | null | undefined;
+    };
+    readonly StudioCMSOAuthAccounts: {
+        readonly providerUserId: string;
+        readonly provider: string;
+        readonly userId: string;
+    };
+    readonly StudioCMSSessionTable: {
+        readonly id: string;
+        readonly userId: string;
+        readonly expiresAt: import("kysely").ColumnType<string, string, string>;
+    };
+    readonly StudioCMSAPIKeys: {
+        readonly id: string;
+        readonly userId: string;
+        readonly key: string;
+        readonly creationDate: import("kysely").ColumnType<string, string | undefined, undefined>;
+        readonly description?: string | null | undefined;
+    };
+    readonly StudioCMSUserResetTokens: {
+        readonly id: string;
+        readonly userId: string;
+        readonly token: string;
+    };
+    readonly StudioCMSPermissions: {
+        readonly user: string;
+        readonly rank: "owner" | "admin" | "editor" | "visitor" | "unknown";
+    };
+    readonly StudioCMSPageFolderStructure: {
+        readonly id: string;
+        readonly name: string;
+        readonly parent?: string | null | undefined;
+    };
+    readonly StudioCMSPageData: {
+        readonly id: string;
+        readonly updatedAt: import("kysely").ColumnType<string, string, string>;
+        readonly description: string;
+        readonly package: string;
+        readonly title: string;
+        readonly showOnNav: number;
+        readonly publishedAt: import("kysely").ColumnType<string, string, string>;
+        readonly slug: string;
+        readonly contentLang: string;
+        readonly categories: import("kysely").ColumnType<string, string, string>;
+        readonly tags: import("kysely").ColumnType<string, string, string>;
+        readonly authorId: string;
+        readonly contributorIds: import("kysely").ColumnType<string, string, string>;
+        readonly showAuthor: number;
+        readonly showContributors: number;
+        readonly draft: number;
+        readonly augments: import("kysely").ColumnType<string, string, string>;
+        readonly heroImage?: string | null | undefined;
+        readonly parentFolder?: string | null | undefined;
+    };
+    readonly StudioCMSDiffTracking: {
+        readonly id: string;
+        readonly userId: string;
+        readonly pageId: string;
+        readonly timestamp: import("kysely").ColumnType<string, string | undefined, undefined>;
+        readonly pageMetaData: import("kysely").ColumnType<string, string, string>;
+        readonly pageContentStart: string;
+        readonly diff?: string | null | undefined;
+    };
+    readonly StudioCMSPageDataTags: {
+        readonly id: number;
+        readonly name: string;
+        readonly description: string;
+        readonly slug: string;
+        readonly meta: import("kysely").ColumnType<string, string, string>;
+    };
+    readonly StudioCMSPageDataCategories: {
+        readonly id: number;
+        readonly name: string;
+        readonly description: string;
+        readonly slug: string;
+        readonly meta: import("kysely").ColumnType<string, string, string>;
+        readonly parent?: number | null | undefined;
+    };
+    readonly StudioCMSPageContent: {
+        readonly id: string;
+        readonly contentLang: string;
+        readonly contentId: string;
+        readonly content: string;
+    };
+    readonly StudioCMSEmailVerificationTokens: {
+        readonly id: string;
+        readonly userId: string;
+        readonly expiresAt: import("kysely").ColumnType<string, string, string>;
+        readonly token: string;
+    };
+    readonly StudioCMSPluginData: {
+        readonly id: string;
+        readonly data: import("kysely").ColumnType<string, string, string>;
+    };
+    readonly StudioCMSDynamicConfigSettings: {
+        readonly id: string;
+        readonly data: import("kysely").ColumnType<string, string, string>;
+    };
+    readonly StudioCMSStorageManagerUrlMappings: {
+        readonly url: string;
+        readonly updatedAt: number;
+        readonly createdAt: import("kysely").ColumnType<number, number | undefined, undefined>;
+        readonly identifier: string;
+        readonly isPermanent: import("kysely").ColumnType<number, boolean, boolean>;
+        readonly expiresAt?: number | null | undefined;
+    };
+}>>;
+/**
+ * Context tag representing the database client interface for StudioCMS.
+ *
+ * This tag can be used to access the database client instance throughout the SDK,
+ * allowing for database operations to be performed in a type-safe manner.
+ */
+export declare class DBClientLive extends DBClientLive_base {
+    /**
+     * Provides a live layer for the DBClient context tag using the given database client.
+     *
+     * @param db - The database client instance to be provided.
+     * @returns A layer that provides the DBClient context tag.
+     */
+    static Live: (db: DBClientInterface<StudioCMSDatabaseSchema>) => Layer.Layer<DBClientLive, never, never>;
+}
+/**
+ * Interface representing the default SDK options.
+ */
+export interface SDKDefaultOpts {
+    GhostUserDefaults: {
+        id: string;
+        name: string;
+        username: string;
+        avatar: string;
+    };
+    NotificationSettingsDefaults: {
+        emailVerification: boolean;
+        oAuthBypassVerification: boolean;
+        requireEditorVerification: boolean;
+        requireAdminVerification: boolean;
+    };
+}
+declare const SDKDefaults_base: Context.TagClass<SDKDefaults, "@withstudiocms/sdk/context/SDKDefaults", SDKDefaultOpts>;
+/**
+ * Context tag representing the default SDK options.
+ *
+ * This tag can be used to access default configuration options for the SDK,
+ * such as default user settings.
+ */
+export declare class SDKDefaults extends SDKDefaults_base {
+    /**
+     * Provides a live layer for the SDKDefaults context tag using the given options.
+     *
+     * @param opts - The options to be provided.
+     * @returns A layer that provides the SDKDefaults context tag.
+     */
+    static live: (opts: SDKDefaultOpts) => Layer.Layer<SDKDefaults, never, never>;
+}
+/**
+ * Interface representing the SDK context, combining the database client and default options.
+ */
+export interface SDKContext {
+    db: DBClientInterface<StudioCMSDatabaseSchema>;
+    defaults: SDKDefaultOpts;
+    cache: {
+        store: Map<string, CacheEntry<unknown>>;
+        tagIndex: Map<string, Set<string>>;
+    };
+    storageManagerResolver: (identifier: string) => Promise<string>;
+}
+declare const CacheStores_base: Context.TagClass<CacheStores, "@withstudiocms/sdk/context/CacheStores", {
+    store: Map<string, CacheEntry<unknown>>;
+    tagIndex: Map<string, Set<string>>;
+}>;
+export declare class CacheStores extends CacheStores_base {
+    static live: (cache: SDKContext["cache"]) => Layer.Layer<CacheStores, never, never>;
+}
+declare const StorageManagerResolver_base: Context.TagClass<StorageManagerResolver, "@withstudiocms/sdk/context/StorageManagerResolver", (identifier: string) => Promise<string>>;
+/**
+ * Context tag representing the storage manager resolver function.
+ *
+ * This tag can be used to access the function responsible for resolving storage manager URLs
+ * based on given identifiers.
+ */
+export declare class StorageManagerResolver extends StorageManagerResolver_base {
+    static live: (resolver: SDKContext["storageManagerResolver"]) => Layer.Layer<StorageManagerResolver, never, never>;
+}
+/**
+ * Combines the database client and SDK default options into a single SDK context layer.
+ *
+ * @param context - An object containing the database client and default SDK options.
+ * @returns A merged layer that provides both the DBClient and SDKDefaults context tags.
+ */
+export declare const makeSDKContext: (context: SDKContext) => Layer.Layer<DBClientLive | SDKDefaults | CacheStores | StorageManagerResolver, never, never>;
+export {};

package/dist/context.js

@@ -0,0 +1,40 @@
+import { Context, Layer } from "@withstudiocms/effect";
+class DBClientLive extends Context.Tag("@withstudiocms/sdk/context/DBClientLive")() {
+  /**
+   * Provides a live layer for the DBClient context tag using the given database client.
+   *
+   * @param db - The database client instance to be provided.
+   * @returns A layer that provides the DBClient context tag.
+   */
+  static Live = (db) => Layer.succeed(this, db);
+}
+class SDKDefaults extends Context.Tag("@withstudiocms/sdk/context/SDKDefaults")() {
+  /**
+   * Provides a live layer for the SDKDefaults context tag using the given options.
+   *
+   * @param opts - The options to be provided.
+   * @returns A layer that provides the SDKDefaults context tag.
+   */
+  static live = (opts) => Layer.succeed(this, opts);
+}
+class CacheStores extends Context.Tag("@withstudiocms/sdk/context/CacheStores")() {
+  static live = (cache) => Layer.succeed(this, cache);
+}
+class StorageManagerResolver extends Context.Tag(
+  "@withstudiocms/sdk/context/StorageManagerResolver"
+)() {
+  static live = (resolver) => Layer.succeed(this, resolver);
+}
+const makeSDKContext = (context) => Layer.mergeAll(
+  DBClientLive.Live(context.db),
+  SDKDefaults.live(context.defaults),
+  CacheStores.live(context.cache),
+  StorageManagerResolver.live(context.storageManagerResolver)
+);
+export {
+  CacheStores,
+  DBClientLive,
+  SDKDefaults,
+  StorageManagerResolver,
+  makeSDKContext
+};

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+declare const StudioCMSSDKError_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: "StudioCMSSDKError";
+} & Readonly<A>;
+export declare class StudioCMSSDKError extends StudioCMSSDKError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,6 @@
+import { Data } from "@withstudiocms/effect";
+class StudioCMSSDKError extends Data.TaggedError("StudioCMSSDKError") {
+}
+export {
+  StudioCMSSDKError
+};