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

package/dist/modules/plugins/index.js

@@ -0,0 +1,261 @@
+import { Effect, Schema } from "@withstudiocms/effect";
+import { StudioCMSPluginData } from "@withstudiocms/kysely";
+import CacheService from "../../cache.js";
+import { cacheKeyGetters, cacheTags } from "../../consts.js";
+import { DBClientLive } from "../../context.js";
+import {
+  parseData,
+  parsedDataResponse,
+  SelectPluginDataRespondOrFail
+} from "../../lib/pluginUtils.js";
+const cacheKey = cacheKeyGetters.plugins;
+const cacheOpts = { tags: cacheTags.plugins };
+const SDKPluginsModule = Effect.gen(function* () {
+  const [{ withCodec }, { memoize, invalidateTags, set }] = yield* Effect.all([
+    DBClientLive,
+    CacheService
+  ]);
+  const _dbBatchRequest = withCodec({
+    encoder: Schema.Struct({
+      batchSize: Schema.Number,
+      offset: Schema.Number
+    }),
+    decoder: Schema.Array(StudioCMSPluginData.Select),
+    callbackFn: (db, { batchSize, offset }) => db(
+      (client) => client.selectFrom("StudioCMSPluginData").selectAll().limit(batchSize).offset(offset).execute()
+    )
+  });
+  const _dbGetEntriesPluginData = withCodec({
+    encoder: Schema.String,
+    decoder: Schema.Array(StudioCMSPluginData.Select),
+    callbackFn: (db, pluginId) => db(
+      (client) => client.selectFrom("StudioCMSPluginData").selectAll().where("id", "like", `${pluginId}-%`).execute()
+    )
+  });
+  const _dbSelectPluginDataEntry = withCodec({
+    encoder: Schema.String,
+    decoder: Schema.UndefinedOr(StudioCMSPluginData.Select),
+    callbackFn: (db, entryId) => db(
+      (client) => client.selectFrom("StudioCMSPluginData").selectAll().where("id", "=", entryId).executeTakeFirst()
+    )
+  });
+  const _dbInsertPluginDataEntry = withCodec({
+    encoder: StudioCMSPluginData.Insert,
+    decoder: StudioCMSPluginData.Select,
+    callbackFn: (db, entry) => db(
+      (client) => client.insertInto("StudioCMSPluginData").values(entry).returningAll().executeTakeFirstOrThrow()
+    )
+  });
+  const _dbUpdatePluginDataEntry = withCodec({
+    encoder: StudioCMSPluginData.Update,
+    decoder: StudioCMSPluginData.Select,
+    callbackFn: (db, entry) => db(
+      (client) => client.updateTable("StudioCMSPluginData").set(entry).where("id", "=", entry.id).returningAll().executeTakeFirstOrThrow()
+    )
+  });
+  const _initPluginDataCache = Effect.fn(
+    (BATCH_SIZE) => Effect.gen(function* () {
+      let batchSize = BATCH_SIZE || 100;
+      if (batchSize <= 0) {
+        batchSize = 100;
+      }
+      let offset = 0;
+      const sharedTimestamp = /* @__PURE__ */ new Date();
+      while (true) {
+        const entries = yield* _dbBatchRequest({ batchSize, offset });
+        if (entries.length === 0) break;
+        const cacheEntries = entries.map(
+          (entry) => [entry.id, { data: entry, lastCacheUpdate: sharedTimestamp }]
+        );
+        for (const [id, cacheData] of cacheEntries) {
+          yield* set(cacheKey(id), cacheData, cacheOpts);
+        }
+        offset += batchSize;
+      }
+    })
+  );
+  const _clearPluginDataCache = Effect.fn(() => invalidateTags(cacheTags.plugins));
+  const _selectPluginDataEntry = Effect.fn(
+    (id) => memoize(cacheKey(id), _dbSelectPluginDataEntry(id), cacheOpts)
+  );
+  const _insertPluginDataEntry = Effect.fn(
+    (data) => memoize(cacheKey(data.id), _dbInsertPluginDataEntry(data), cacheOpts)
+  );
+  const _updatePluginDataEntry = Effect.fn(
+    (data) => memoize(cacheKey(data.id), _dbUpdatePluginDataEntry(data), cacheOpts)
+  );
+  const _processEntryFromDB = Effect.fn(
+    (entry, validator) => parseData(entry.data, validator).pipe(
+      Effect.flatMap((validated) => parsedDataResponse(entry.id, validated))
+    )
+  );
+  const _processPluginDataDBEntries = (validator) => Effect.fn(
+    (entries) => Effect.all(entries.map((entry) => _processEntryFromDB(entry, validator)))
+  );
+  const _filterProcessedEntries = (filter) => (entries) => filter ? filter(entries) : entries;
+  const _getEntries = Effect.fn(
+    (pluginId, validator, filter) => _dbGetEntriesPluginData(pluginId).pipe(
+      Effect.flatMap(_processPluginDataDBEntries(validator)),
+      Effect.map(_filterProcessedEntries(filter))
+    )
+  );
+  const _selectPluginDataEntryRespondOrFail = Effect.fn(function* (id, mode) {
+    const existing = yield* _selectPluginDataEntry(id);
+    switch (mode) {
+      case SelectPluginDataRespondOrFail.ExistsNoFail: {
+        if (existing) return existing;
+        return void 0;
+      }
+      case SelectPluginDataRespondOrFail.ExistsShouldFail: {
+        if (existing)
+          return yield* Effect.fail(new Error(`Plugin data with ID ${id} already exists.`));
+        return void 0;
+      }
+      case SelectPluginDataRespondOrFail.NotExistsShouldFail: {
+        if (!existing)
+          return yield* Effect.fail(new Error(`Plugin data with ID ${id} does not exist.`));
+        return void 0;
+      }
+      default:
+        return yield* Effect.fail(new Error(`Invalid mode: ${mode}`));
+    }
+  });
+  const _select = Effect.fn(function* (generatedEntryId, validator) {
+    const existing = yield* _selectPluginDataEntryRespondOrFail(
+      generatedEntryId,
+      SelectPluginDataRespondOrFail.ExistsNoFail
+    );
+    if (!existing) return void 0;
+    const data = yield* parseData(existing.data, validator);
+    return yield* parsedDataResponse(generatedEntryId, data);
+  });
+  const _insert = Effect.fn(function* (generatedEntryId, data, validator) {
+    yield* _selectPluginDataEntryRespondOrFail(
+      generatedEntryId,
+      SelectPluginDataRespondOrFail.ExistsShouldFail
+    );
+    const parsedData = yield* parseData(data, validator);
+    const inserted = yield* _insertPluginDataEntry({
+      id: generatedEntryId,
+      data: JSON.stringify(parsedData)
+    });
+    return yield* parsedDataResponse(inserted.id, parsedData);
+  });
+  const _update = Effect.fn(function* (generatedEntryId, data, validator) {
+    yield* _selectPluginDataEntryRespondOrFail(
+      generatedEntryId,
+      SelectPluginDataRespondOrFail.NotExistsShouldFail
+    );
+    const parsedData = yield* parseData(data, validator);
+    const updated = yield* _updatePluginDataEntry({
+      id: generatedEntryId,
+      data: JSON.stringify(parsedData)
+    });
+    return yield* parsedDataResponse(updated.id, parsedData);
+  });
+  const buildReturn = (pluginId, entryId, validator) => {
+    const generatedEntryId = `${pluginId}-${entryId}`;
+    return {
+      /**
+       * Generates a unique ID for the plugin data entry.
+       *
+       * @returns An Effect that yields the generated ID. In the format `${pluginId}-${entryId}`
+       */
+      generatedId: () => Effect.succeed(generatedEntryId),
+      /**
+       * Selects a plugin data entry by its ID, validating the data if a validator is provided.
+       *
+       * @returns An Effect that yields the selected plugin data entry or `undefined` if not found.
+       */
+      select: () => _select(generatedEntryId, validator),
+      /**
+       * Inserts new plugin data into the database after validating the input.
+       *
+       * @param data - The plugin data to insert.
+       * @yields Throws an error if validation fails or if the entry already exists.
+       * @returns The parsed data response for the inserted entry.
+       */
+      insert: (data) => _insert(generatedEntryId, data, validator),
+      /**
+       * Updates existing plugin data in the database after validating the input.
+       *
+       * @param data - The updated plugin data.
+       * @yields Throws an error if validation fails.
+       * @returns The parsed data response for the updated entry.
+       */
+      update: (data) => _update(generatedEntryId, data, validator)
+    };
+  };
+  function usePluginData(pluginId, { entryId, validator } = {}) {
+    if (!entryId) {
+      return {
+        /**
+         * Retrieves all plugin data entries for the specified plugin ID.
+         *
+         * @template T - The type of the plugin data object.
+         * @param validator - Optional validator options for validating the plugin data.
+         * @returns An Effect that yields an array of `PluginDataEntry<T>` objects.
+         */
+        getEntries: (filter) => _getEntries(pluginId, validator, filter),
+        getEntry: (id) => buildReturn(pluginId, id, validator)
+      };
+    }
+    return buildReturn(pluginId, entryId, validator);
+  }
+  class InferType {
+    _Schema;
+    $UsePluginData;
+    $Insert;
+    constructor(schema) {
+      if (!schema || !Schema.isSchema(schema)) {
+        throw new Error("InferType requires a valid Schema.Struct instance.");
+      }
+      this._Schema = schema;
+    }
+  }
+  return {
+    /**
+     * 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,
+    /**
+     * Initializes the plugin data cache by fetching all existing entries from the database
+     * and populating the in-memory cache with these entries.
+     */
+    initPluginDataCache: _initPluginDataCache,
+    /**
+     * Clears the plugin data cache, removing all cached entries.
+     *
+     * @returns An Effect that resolves to `void` on success or an `Error` on failure.
+     */
+    clearPluginDataCache: _clearPluginDataCache,
+    /**
+     * 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
+  };
+});
+var plugins_default = SDKPluginsModule;
+export {
+  SDKPluginsModule,
+  plugins_default as default
+};

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

@@ -0,0 +1,305 @@
+import { Effect } from '@withstudiocms/effect';
+import { DBCallbackFailure, StudioCMSPageData, StudioCMSPermissions } from '@withstudiocms/kysely';
+import CacheService from '../../cache.js';
+import { DBClientLive } from '../../context.js';
+import type { CombinedInsertContent } from '../../types.js';
+/**
+ * Represents the data required to insert a new page.
+ */
+export interface PageInsert {
+    pageData: OptionalId<string, (typeof StudioCMSPageData)['Insert']['Type']>;
+    pageContent: CombinedInsertContent;
+}
+/**
+ * Represents an array of PageInsert objects.
+ */
+export type MultiPageInsert = PageInsert[];
+/**
+ * Utility type to make the 'id' property optional in a given type T.
+ *
+ * @template IDType - The type of the 'id' property.
+ * @template T - The original type containing the 'id' property.
+ */
+export type OptionalId<IDType, T> = Omit<T, 'id'> & {
+    id?: IDType;
+};
+/**
+ * Error class representing an existing permission for a user.
+ */
+export declare class PermissionExistsError {
+    readonly _tag = "PermissionExistsError";
+}
+/**
+ * SDKPostModule
+ *
+ * Effect generator that builds and returns the post/page-related SDK surface for database
+ * insert operations and related helpers. This module wires together database client and
+ * auxiliary services (clear/update/get/generator/cache) and exposes both single- and
+ * batch-oriented insertion APIs plus higher-level "main" operations that also trigger
+ * cache invalidation and UI updates.
+ *
+ * Remarks
+ * - The generator yields the following dependencies: DBClientLive, SDKClearModule,
+ *   SDKUpdateModule, SDKGetModule, SDKGenerators, CacheService.
+ * - Low-level DB insert wrappers are created with `withCodec` and perform SQL operations
+ *   against tables such as StudioCMSPageData, StudioCMSPageContent, StudioCMSPageDataTags,
+ *   StudioCMSPageDataCategories, StudioCMSPermissions, StudioCMSDiffTracking,
+ *   StudioCMSPageFolderStructure.
+ * - Helpers use Effect primitives (pipe, flatMap, tap, all, catchTag, succeed, fail)
+ *   and utilities such as `crypto.randomUUID()` and a numeric id generator
+ *   (`generateRandomIDNumber`) to ensure IDs when not provided.
+ * - Cache invalidation is performed via `invalidateTags(cacheTags.pages)` and certain
+ *   operations also call `clear.*` and `update.*` to refresh derived state such as
+ *   folder lists/trees.
+ * - Duplicate permission insertion is guarded: attempting to insert a permission for a
+ *   user that already exists results in a PermissionExistsError which is mapped to a
+ *   DBCallbackFailure with a descriptive message.
+ *
+ * Exposed API (returned object)
+ * - databaseEntry: object containing single-entry insert effects:
+ *   - pages(pageData, pageContent): insert a page and its content (returns inserted ids)
+ *   - pageContent(data): insert page content entry
+ *   - tags(tag): insert a tag (ensures id)
+ *   - categories(category): insert a category (ensures id)
+ *   - permissions(userId, rank): insert a permission for a user (fails if already exists)
+ *   - diffTracking(data): insert diff-tracking entry (ensures id)
+ *   - folder(data): insert a folder structure entry (ensures id)
+ * - databaseEntries: object containing batch insert effects:
+ *   - tags(array): insert multiple tags
+ *   - categories(array): insert multiple categories
+ *   - permissions(array): insert multiple permissions
+ *   - pages(array): insert multiple pages with content
+ * - folder: higher-level folder insert that triggers update.folderList and update.folderTree
+ * - page: higher-level page insert that clears folder caches, invalidates page cache tags,
+ *   and returns the freshly-read page via GET.page.byId
+ *
+ * Errors
+ * - DB operations propagate database-level errors from the SQL client.
+ * - Permission insertion collides are translated to DBCallbackFailure with a human-friendly
+ *   cause string.
+ *
+ * Returns
+ * - An Effect that, when executed, yields the assembled API object described above.
+ */
+export declare const SDKPostModule: Effect.Effect<{
+    databaseEntry: {
+        /**
+         * Inserts a new page along with its content into the database.
+         *
+         * @param pageData - The data for the new page, excluding the ID.
+         * @param pageContent - The content for the new page.
+         * @returns An effect that resolves to an object containing the IDs of the newly inserted page data and content.
+         */
+        pages: (pageData: OptionalId<string, {
+            readonly tags: string;
+            readonly id: string;
+            readonly description: string;
+            readonly slug: string;
+            readonly contentLang: string;
+            readonly updatedAt: string;
+            readonly package: string;
+            readonly title: string;
+            readonly showOnNav: boolean;
+            readonly publishedAt: string;
+            readonly heroImage: string | null | undefined;
+            readonly categories: string;
+            readonly authorId: string;
+            readonly contributorIds: string;
+            readonly showAuthor: boolean;
+            readonly showContributors: boolean;
+            readonly parentFolder: string | null | undefined;
+            readonly draft: boolean;
+            readonly augments: string;
+        }>, pageContent: CombinedInsertContent) => Effect.Effect<{
+            pageData: {
+                readonly id: string;
+            };
+            pageContent: {
+                readonly id: string;
+            };
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Inserts a new page content entry into the database.
+         *
+         * @param data - The page content data to be inserted.
+         * @returns An effect that resolves to the ID of the newly inserted page content.
+         */
+        pageContent: (input: {
+            readonly id: string;
+            readonly contentId: string;
+            readonly contentLang: string;
+            readonly content: string;
+        }) => Effect.Effect<{
+            readonly id: string;
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Inserts a new page data tag into the database.
+         *
+         * @param tag - The tag data to be inserted.
+         * @returns An effect that resolves to the ID of the newly inserted tag.
+         */
+        tags: (tag: OptionalId<number, {
+            readonly name: string;
+            readonly id: number;
+            readonly description: string;
+            readonly slug: string;
+            readonly meta: string;
+        }>) => Effect.Effect<{
+            readonly id: number;
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError | import("../util/generators.js").GeneratorError, never>;
+        /**
+         * Inserts a new page data category into the database.
+         *
+         * @param category - The category data to be inserted.
+         * @returns An effect that resolves to the ID of the newly inserted category.
+         */
+        categories: (category: OptionalId<number, {
+            readonly name: string;
+            readonly id: number;
+            readonly parent: number | null | undefined;
+            readonly description: string;
+            readonly slug: string;
+            readonly meta: string;
+        }>) => Effect.Effect<{
+            readonly id: number;
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError | import("../util/generators.js").GeneratorError, never>;
+        /**
+         * Inserts a new permission entry for a user into the database.
+         *
+         * @param userId - The ID of the user for whom the permission is to be created.
+         * @param rank - The rank of the permission to be assigned.
+         * @returns An effect that resolves to the newly inserted permission entry.
+         */
+        permissions: (userId: string, rank: "owner" | "admin" | "editor" | "visitor" | "unknown") => Effect.Effect<{
+            readonly user: string;
+            readonly rank: "owner" | "admin" | "editor" | "visitor" | "unknown";
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Inserts a new diff tracking entry into the database.
+         *
+         * @param data - The diff tracking data to be inserted.
+         * @returns An effect that resolves to the newly inserted diff tracking entry.
+         */
+        diffTracking: (data: OptionalId<string, {
+            readonly id: string;
+            readonly userId: string;
+            readonly pageMetaData: string;
+            readonly pageId: string;
+            readonly timestamp: string | undefined;
+            readonly pageContentStart: string;
+            readonly diff: string | null | undefined;
+        }>) => Effect.Effect<{
+            readonly id: string;
+            readonly userId: string;
+            readonly pageMetaData: {
+                readonly [x: string]: unknown;
+            };
+            readonly pageId: string;
+            readonly timestamp: Date;
+            readonly pageContentStart: string;
+            readonly diff: string | null | undefined;
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Inserts a new folder structure entry into the database.
+         *
+         * @param data - The folder structure data to be inserted.
+         * @returns An effect that resolves to the newly inserted folder structure entry.
+         */
+        folder: (data: OptionalId<string, {
+            readonly name: string;
+            readonly id: string;
+            readonly parent: string | null | undefined;
+        }>) => Effect.Effect<{
+            readonly name: string;
+            readonly id: string;
+            readonly parent: string | null | undefined;
+        }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+    };
+    databaseEntries: {
+        /**
+         * Inserts an array of new page data tags into the database.
+         *
+         * @param tags - The array of tag data to be inserted.
+         * @returns An effect that resolves to an array of IDs of the newly inserted tags.
+         */
+        tags: (tags: OptionalId<number, {
+            readonly name: string;
+            readonly id: number;
+            readonly description: string;
+            readonly slug: string;
+            readonly meta: string;
+        }>[]) => Effect.Effect<{
+            readonly id: number;
+        }[], DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError | import("../util/generators.js").GeneratorError, never>;
+        /**
+         * Inserts an array of new page data categories into the database.
+         *
+         * @param categories - The array of category data to be inserted.
+         * @returns An effect that resolves to an array of IDs of the newly inserted categories.
+         */
+        categories: (categories: OptionalId<number, {
+            readonly name: string;
+            readonly id: number;
+            readonly parent: number | null | undefined;
+            readonly description: string;
+            readonly slug: string;
+            readonly meta: string;
+        }>[]) => Effect.Effect<{
+            readonly id: number;
+        }[], DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError | import("../util/generators.js").GeneratorError, never>;
+        /**
+         * Inserts an array of new permissions into the database.
+         *
+         * @param permissions - The array of permission data to be inserted.
+         * @returns An effect that resolves to an array of newly inserted permission entries.
+         */
+        permissions: (permissions: {
+            userId: string;
+            rank: (typeof StudioCMSPermissions.Insert.Type)["rank"];
+        }[]) => Effect.Effect<{
+            readonly user: string;
+            readonly rank: "owner" | "admin" | "editor" | "visitor" | "unknown";
+        }[], DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Inserts an array of new pages along with their content into the database.
+         *
+         * @param data - An array of PageInsert objects containing page data and content.
+         * @returns An effect that resolves to an array of objects containing the IDs of the newly inserted page data and content for each page.
+         */
+        pages: (pages: MultiPageInsert) => Effect.Effect<{
+            pageData: {
+                readonly id: string;
+            };
+            pageContent: {
+                readonly id: string;
+            };
+        }[], DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+    };
+    /**
+     * Inserts a new folder structure entry into the database, ensuring it has an ID.
+     *
+     * @param data - The folder structure data to be inserted.
+     * @returns An effect that resolves to the newly inserted folder structure entry.
+     */
+    folder: (data: OptionalId<string, {
+        readonly name: string;
+        readonly id: string;
+        readonly parent: string | null | undefined;
+    }>) => Effect.Effect<{
+        readonly name: string;
+        readonly id: string;
+        readonly parent: string | null | undefined;
+    }, DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError | import("../util/folderTree.js").FolderTreeError, never>;
+    /**
+     * Inserts a new page along with its content into the database.
+     *
+     * @param pageData - The data for the new page, excluding the ID.
+     * @param pageContent - The content for the new page.
+     * @returns An effect that resolves to the newly inserted page data.
+     */
+    page: (args_0: {
+        pageData: OptionalId<string, (typeof StudioCMSPageData)["Insert"]["Type"]>;
+        pageContent: CombinedInsertContent;
+    }) => Effect.Effect<import("../../types.js").CombinedPageData | undefined, import("effect/ParseResult").ParseError | 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>;
+}, import("effect/ConfigError").ConfigError, DBClientLive | import("../../context.js").SDKDefaults | CacheService | import("@withstudiocms/effect").Deepmerge>;
+export default SDKPostModule;