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

package/dist/modules/post/index.js

@@ -0,0 +1,305 @@
+import { Effect, pipe, Schema } from "@withstudiocms/effect";
+import {
+  DBCallbackFailure,
+  StudioCMSDiffTracking,
+  StudioCMSPageContent,
+  StudioCMSPageData,
+  StudioCMSPageDataCategories,
+  StudioCMSPageDataTags,
+  StudioCMSPageFolderStructure,
+  StudioCMSPermissions
+} from "@withstudiocms/kysely";
+import CacheService from "../../cache.js";
+import { cacheTags } from "../../consts.js";
+import { DBClientLive } from "../../context.js";
+import SDKClearModule from "../clear/index.js";
+import SDKGetModule from "../get/index.js";
+import SDKUpdateModule from "../update/index.js";
+import { SDKGenerators } from "../util/generators.js";
+class PermissionExistsError {
+  _tag = "PermissionExistsError";
+}
+const SDKPostModule = Effect.gen(function* () {
+  const [{ withCodec }, clear, update, GET, { generateRandomIDNumber }, { invalidateTags }] = yield* Effect.all([
+    DBClientLive,
+    SDKClearModule,
+    SDKUpdateModule,
+    SDKGetModule,
+    SDKGenerators,
+    CacheService
+  ]);
+  const _insertPageData = withCodec({
+    encoder: StudioCMSPageData.Insert,
+    decoder: Schema.Struct({
+      id: Schema.String
+    }),
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSPageData").values(data).returning("id").executeTakeFirstOrThrow()
+    )
+  });
+  const _insertPageContent = withCodec({
+    encoder: StudioCMSPageContent.Insert,
+    decoder: Schema.Struct({
+      id: Schema.String
+    }),
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSPageContent").values(data).returning("id").executeTakeFirstOrThrow()
+    )
+  });
+  const _insertTagData = withCodec({
+    encoder: StudioCMSPageDataTags.Insert,
+    decoder: Schema.Struct({
+      id: Schema.Number
+    }),
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSPageDataTags").values(data).returning("id").executeTakeFirstOrThrow()
+    )
+  });
+  const _insertCategoryData = withCodec({
+    encoder: StudioCMSPageDataCategories.Insert,
+    decoder: Schema.Struct({
+      id: Schema.Number
+    }),
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSPageDataCategories").values(data).returning("id").executeTakeFirstOrThrow()
+    )
+  });
+  const _getUserPermission = withCodec({
+    encoder: Schema.String,
+    decoder: StudioCMSPermissions.Select,
+    callbackFn: (db, userId) => db(
+      (client) => client.selectFrom("StudioCMSPermissions").selectAll().where("user", "=", userId).executeTakeFirstOrThrow()
+    )
+  });
+  const _insertNewUserPermission = withCodec({
+    encoder: StudioCMSPermissions.Insert,
+    decoder: StudioCMSPermissions.Select,
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSPermissions").values(data).returningAll().executeTakeFirstOrThrow()
+    )
+  });
+  const _insertNewDiffTracking = withCodec({
+    encoder: StudioCMSDiffTracking.Insert,
+    decoder: StudioCMSDiffTracking.Select,
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSDiffTracking").values(data).returningAll().executeTakeFirstOrThrow()
+    )
+  });
+  const _insertNewFolder = withCodec({
+    encoder: StudioCMSPageFolderStructure.Insert,
+    decoder: StudioCMSPageFolderStructure.Select,
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSPageFolderStructure").values(data).returningAll().executeTakeFirstOrThrow()
+    )
+  });
+  const _randomUUIDString = Effect.fn(() => Effect.succeed(crypto.randomUUID().toString()));
+  const _pageDataIdOrGenerateUUID = Effect.fn(function* (data) {
+    const id = data.id || (yield* _randomUUIDString());
+    return { id, ...data };
+  });
+  const _insertNewPageWithContent = Effect.fn(
+    (pageData, pageContent) => Effect.all({
+      pageData: _pageDataIdOrGenerateUUID(pageData),
+      pageContent: Effect.succeed(pageContent)
+    }).pipe(
+      Effect.flatMap(
+        ({ pageData: { id, contentLang, ...basePageData }, pageContent: pageContent2 }) => Effect.all({
+          pageData: _insertPageData({
+            ...basePageData,
+            id,
+            contentLang
+          }),
+          pageContent: _insertPageContent({
+            id: crypto.randomUUID().toString(),
+            contentId: id,
+            contentLang,
+            content: pageContent2.content || ""
+          })
+        })
+      ),
+      Effect.tap(() => invalidateTags(cacheTags.pages))
+    )
+  );
+  const _insertPageWithContentArray = Effect.fn(
+    (pages) => Effect.all(
+      pages.map(({ pageData, pageContent }) => _insertNewPageWithContent(pageData, pageContent))
+    )
+  );
+  const _pickIdOrGenerate = Effect.fn(function* (data) {
+    const id = data.id || (yield* generateRandomIDNumber(9));
+    return { id, ...data };
+  });
+  const _insertNewTag = Effect.fn(
+    (tag) => _pickIdOrGenerate(tag).pipe(Effect.flatMap(_insertTagData))
+  );
+  const _insertTagArray = Effect.fn(
+    (tags) => Effect.all(tags.map((tag) => _insertNewTag(tag)))
+  );
+  const _insertNewCategory = Effect.fn(
+    (category) => _pickIdOrGenerate(category).pipe(Effect.flatMap(_insertCategoryData))
+  );
+  const _insertCategoryArray = Effect.fn(
+    (categories) => Effect.all(categories.map((category) => _insertNewCategory(category)))
+  );
+  const _insertNewPermission = Effect.fn(
+    (userId, rank) => _getUserPermission(userId).pipe(
+      Effect.flatMap(
+        (exists) => exists ? Effect.fail(new PermissionExistsError()) : Effect.succeed({ user: userId, rank })
+      ),
+      Effect.flatMap((data) => _insertNewUserPermission(data)),
+      Effect.catchTag(
+        "PermissionExistsError",
+        () => Effect.fail(
+          new DBCallbackFailure({
+            cause: "Permission for user already exists, Please update instead."
+          })
+        )
+      )
+    )
+  );
+  const _insertPermissionArray = Effect.fn(
+    (permissions) => Effect.all(permissions.map(({ userId, rank }) => _insertNewPermission(userId, rank)))
+  );
+  const _insertDiffTracking = Effect.fn(
+    (data) => pipe(
+      data.id ? Effect.succeed(data) : _randomUUIDString().pipe(Effect.map((id) => ({ id, ...data }))),
+      Effect.flatMap((dataWithId) => _insertNewDiffTracking(dataWithId))
+    )
+  );
+  const _insertFolder = Effect.fn(
+    (data) => pipe(
+      data.id ? Effect.succeed(data) : _randomUUIDString().pipe(Effect.map((id) => ({ id, ...data }))),
+      Effect.flatMap((dataWithId) => _insertNewFolder(dataWithId))
+    )
+  );
+  const _mainInsertFolder = Effect.fn(
+    (data) => _insertFolder(data).pipe(Effect.tap(() => Effect.all([update.folderList, update.folderTree])))
+  );
+  const _mainInsertPage = Effect.fn(
+    ({
+      pageData,
+      pageContent
+    }) => _insertNewPageWithContent(pageData, pageContent).pipe(
+      Effect.flatMap(({ pageData: { id } }) => GET.page.byId(id)),
+      Effect.tap(
+        () => Effect.all([
+          clear.folderList,
+          clear.folderTree,
+          invalidateTags([
+            ...cacheTags.pages,
+            ...cacheTags.pageFolderTree,
+            ...cacheTags.folderTree
+          ])
+        ])
+      )
+    )
+  );
+  const 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: _insertNewPageWithContent,
+    /**
+     * 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: _insertPageContent,
+    /**
+     * 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: _insertNewTag,
+    /**
+     * 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: _insertNewCategory,
+    /**
+     * 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: _insertNewPermission,
+    /**
+     * 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: _insertDiffTracking,
+    /**
+     * 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: _insertFolder
+  };
+  const 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: _insertTagArray,
+    /**
+     * 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: _insertCategoryArray,
+    /**
+     * 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: _insertPermissionArray,
+    /**
+     * 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: _insertPageWithContentArray
+  };
+  return {
+    databaseEntry,
+    databaseEntries,
+    /**
+     * 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: _mainInsertFolder,
+    /**
+     * 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: _mainInsertPage
+  };
+});
+var post_default = SDKPostModule;
+export {
+  PermissionExistsError,
+  SDKPostModule,
+  post_default as default
+};

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

@@ -0,0 +1,91 @@
+import { Effect } from '@withstudiocms/effect';
+import { type DBCallbackFailure } from '@withstudiocms/kysely';
+import type { DatabaseError } from '@withstudiocms/kysely/core/errors';
+import { DBClientLive } from '../../context.js';
+/**
+ * Error class representing a failure in the reset token bucket operations.
+ */
+export declare class resetTokenBucketFail {
+    readonly _tag = "resetTokenBucketFail";
+}
+/**
+ * SDKResetTokenBucketModule
+ *
+ * Effectful module that provides reset-token management backed by the application database
+ * and a JWT-based token generator/verifier. The module is constructed as an Effect generator
+ * and depends on the DB client layer and token-generation/test utilities (resolved via
+ * DBClientLive and SDKGenerators).
+ *
+ * The resolved value is an object exposing three primary operations:
+ * - new(userId: string): Effect<E, Error, StudioCMSUserResetTokens.Select.Type>
+ *     - Generates a cryptographically strong token for the supplied userId, persists a new
+ *       reset-token record (with a generated UUID id and the token string) into the
+ *       StudioCMSUserResetTokens table, and returns the inserted DB record.
+ *     - Side effects: inserts into the DB, uses token-generation service.
+ *     - Errors: database errors or generator errors may be raised by the returned effect.
+ *
+ * - delete(userId: string): Effect<E, Error, void>
+ *     - Deletes any reset-token record(s) associated with the supplied userId.
+ *     - Side effects: deletes from the DB.
+ *     - Errors: database errors may be raised by the returned effect.
+ *
+ * - check(token: string): Effect<E, never, boolean>
+ *     - Verifies whether the provided token is valid and matches the currently stored
+ *       reset-token for the associated user:
+ *       1. Validates and verifies the token using the token verifier.
+ *       2. Retrieves the stored token record for the userId extracted from the token.
+ *       3. Compares the stored token string to the provided token and returns true/false.
+ *     - The method treats invalid token verification as a domain failure type
+ *       (resetTokenBucketFail) internally; that failure is caught and normalized to `false`.
+ *     - Side effects: reads from the DB, uses token verification service.
+ *     - Errors: unexpected runtime/database errors may still surface from the returned effect.
+ *
+ * Remarks:
+ * - The implementation uses codec- and encoder-wrappers for DB interactions (encoders/decoders
+ *   for StudioCMSUserResetTokens) to ensure schema conformance on read/write.
+ * - Token creation uses a generated UUID for the DB record id and a generator service for the
+ *   token payload. Token verification relies on the provided testToken function (from SDKGenerators).
+ * - The `check` operation intentionally swallows the domain-level `resetTokenBucketFail` and
+ *   returns `false` to represent invalid/malformed tokens as a boolean outcome; other errors
+ *   (e.g. DB connectivity) are not masked.
+ *
+ * Example:
+ * const resetBucket = yield* Effect.runPromise(SDKResetTokenBucketModule);
+ * await Effect.runPromise(resetBucket.new("user-id"));
+ * const isValid = await Effect.runPromise(resetBucket.check("token-string"));
+ *
+ * Type parameters and environment:
+ * - The module itself is returned as an Effect and therefore requires the Effect environment
+ *   that provides the DB and token generator/test layers. Consumers should provide those
+ *   dependencies when running the effect.
+ *
+ * @public
+ */
+export declare const SDKResetTokenBucketModule: Effect.Effect<{
+    /**
+     * Creates a new reset token for the specified user.
+     *
+     * @param userId - The ID of the user for whom to create the reset token.
+     * @returns An effect yielding the created reset token record.
+     */
+    new: (userId: string) => Effect.Effect<{
+        readonly id: string;
+        readonly userId: string;
+        readonly token: string;
+    }, DBCallbackFailure | DatabaseError | import("../util/generators.js").GeneratorError, never>;
+    /**
+     * Deletes the reset token for the specified user.
+     *
+     * @param userId - The ID of the user for whom to delete the reset token.
+     * @returns An effect yielding the result of the delete operation.
+     */
+    delete: (input: string) => Effect.Effect<import("kysely").DeleteResult[], DBCallbackFailure | DatabaseError, never>;
+    /**
+     * Checks if the specified reset token is valid.
+     *
+     * @param token - The reset token to check.
+     * @returns An effect yielding a boolean indicating whether the token is valid.
+     */
+    check: (token: string) => Effect.Effect<boolean, DBCallbackFailure | DatabaseError | import("../util/generators.js").GeneratorError, never>;
+}, import("effect/ConfigError").ConfigError, DBClientLive>;
+export default SDKResetTokenBucketModule;

package/dist/modules/resetTokenBucket/index.js

@@ -0,0 +1,93 @@
+import { Effect, Schema } from "@withstudiocms/effect";
+import { StudioCMSUserResetTokens } from "@withstudiocms/kysely";
+import { DBClientLive } from "../../context.js";
+import { SDKGenerators } from "../util/generators.js";
+class resetTokenBucketFail {
+  _tag = "resetTokenBucketFail";
+}
+const SDKResetTokenBucketModule = Effect.gen(function* () {
+  const [{ withCodec, withEncoder }, { generateToken, testToken }] = yield* Effect.all([
+    DBClientLive,
+    SDKGenerators
+  ]);
+  const _createNewToken = withCodec({
+    encoder: StudioCMSUserResetTokens.Insert,
+    decoder: StudioCMSUserResetTokens.Select,
+    callbackFn: (db, data) => db(
+      (client) => client.insertInto("StudioCMSUserResetTokens").values(data).returningAll().executeTakeFirstOrThrow()
+    )
+  });
+  const _deleteTokenByUserId = withEncoder({
+    encoder: Schema.String,
+    callbackFn: (db, userId) => db(
+      (client) => client.deleteFrom("StudioCMSUserResetTokens").where("userId", "=", userId).execute()
+    )
+  });
+  const _getTokenByUserId = withCodec({
+    encoder: Schema.String,
+    decoder: Schema.UndefinedOr(StudioCMSUserResetTokens.Select),
+    callbackFn: (db, userId) => db(
+      (client) => client.selectFrom("StudioCMSUserResetTokens").selectAll().where("userId", "=", userId).executeTakeFirst()
+    )
+  });
+  const _createUserResetToken = Effect.fn(
+    (userId) => generateToken(userId).pipe(
+      Effect.flatMap(
+        (token) => _createNewToken({
+          id: crypto.randomUUID(),
+          userId,
+          token
+        })
+      )
+    )
+  );
+  const _checkIfValid = Effect.fn(
+    (token) => !token.isValid || !token.userId ? Effect.fail(new resetTokenBucketFail()) : Effect.succeed(token)
+  );
+  const _getTokenInfo = Effect.fn(
+    ({
+      userId
+    }) => userId ? _getTokenByUserId(userId) : Effect.fail(new resetTokenBucketFail())
+  );
+  const _verifyTokenMatch = (token) => Effect.fn(
+    (resetToken) => resetToken ? Effect.succeed(resetToken.token === token) : Effect.fail(new resetTokenBucketFail())
+  );
+  const _checkToken = Effect.fn(
+    (token) => testToken(token).pipe(
+      Effect.flatMap(_checkIfValid),
+      Effect.flatMap(_getTokenInfo),
+      Effect.flatMap(_verifyTokenMatch(token)),
+      Effect.catchTag("resetTokenBucketFail", () => Effect.succeed(false))
+    )
+  );
+  const resetTokenBucket = {
+    /**
+     * Creates a new reset token for the specified user.
+     *
+     * @param userId - The ID of the user for whom to create the reset token.
+     * @returns An effect yielding the created reset token record.
+     */
+    new: _createUserResetToken,
+    /**
+     * Deletes the reset token for the specified user.
+     *
+     * @param userId - The ID of the user for whom to delete the reset token.
+     * @returns An effect yielding the result of the delete operation.
+     */
+    delete: _deleteTokenByUserId,
+    /**
+     * Checks if the specified reset token is valid.
+     *
+     * @param token - The reset token to check.
+     * @returns An effect yielding a boolean indicating whether the token is valid.
+     */
+    check: _checkToken
+  };
+  return resetTokenBucket;
+});
+var resetTokenBucket_default = SDKResetTokenBucketModule;
+export {
+  SDKResetTokenBucketModule,
+  resetTokenBucket_default as default,
+  resetTokenBucketFail
+};

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

@@ -0,0 +1,92 @@
+import { Effect } from '@withstudiocms/effect';
+import { DBClientLive } from '../../context.js';
+/**
+ * SDKRestAPIModule
+ *
+ * Effect-based module that provides REST API operations for managing StudioCMS API keys and verifying tokens.
+ *
+ * @remarks
+ * - Composed with DBClientLive and SDKGenerators (exposes withCodec, withEncoder and generateToken).
+ * - Persists and queries data against the 'StudioCMSAPIKeys' and 'StudioCMSPermissions' tables.
+ * - All public operations are provided as Effects and use runtime codecs/encoders for input/output validation.
+ * - New keys are generated via the provided generator and persisted with a UUID created by crypto.randomUUID().
+ *
+ * Exposed surface (tokens):
+ * - tokens.get(userId: string): Effect<StudioCMSAPIKeys.Select[]>
+ *   Retrieves all API tokens for the specified user.
+ *
+ * - tokens.new(userId: string, description: string): Effect<StudioCMSAPIKeys.Select>
+ *   Generates a new API key for the given user, persists it, and returns the created record.
+ *
+ * - tokens.delete({ userId: string; tokenId: string }): Effect<void>
+ *   Deletes the specified API token for the user.
+ *
+ * - tokens.verify(key: string): Effect<{ userId: string; key: string; rank: number } | false>
+ *   Validates the provided API key. If valid, returns the associated userId, key and permission rank; otherwise returns false.
+ *
+ * @returns An Effect that resolves to an object containing the `tokens` API.
+ *
+ * @example
+ * // Usage (conceptual)
+ * const { tokens } = yield* SDKRestAPIModule;
+ * const created = yield* tokens.new('user-123', 'automation key');
+ * const all = yield* tokens.get('user-123');
+ * const infoOrFalse = yield* tokens.verify(created.key);
+ */
+export declare const SDKRestAPIModule: Effect.Effect<{
+    tokens: {
+        /**
+         * Retrieves all API tokens for a specific user.
+         *
+         * @param userId - The ID of the user whose tokens are to be retrieved.
+         * @returns An Effect that resolves to an array of API keys for the user.
+         * @throws {LibSQLDatabaseError} If a database error occurs during the operation.
+         */
+        get: (input: string) => Effect.Effect<readonly {
+            readonly key: string;
+            readonly id: string;
+            readonly description: string | null | undefined;
+            readonly userId: string;
+            readonly creationDate: Date;
+        }[], import("@withstudiocms/kysely").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Creates a new API token for a user with the specified description.
+         *
+         * @param userId - The ID of the user for whom to create the token.
+         * @param description - A description for the API key.
+         * @returns An Effect that resolves to the created API key record.
+         * @throws {LibSQLDatabaseError} If a database error occurs during the operation.
+         */
+        new: (userId: string, description: string) => Effect.Effect<{
+            readonly key: string;
+            readonly id: string;
+            readonly description: string | null | undefined;
+            readonly userId: string;
+            readonly creationDate: Date;
+        }, import("@withstudiocms/kysely").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError | import("../util/generators.js").GeneratorError, never>;
+        /**
+         * Deletes an API token for a user by its ID.
+         *
+         * @param userId - The ID of the user whose token is to be deleted.
+         * @param tokenId - The ID of the API token to delete.
+         * @returns An Effect that resolves when the token is successfully deleted.
+         * @throws {LibSQLDatabaseError} If a database error occurs during the operation.
+         */
+        delete: (input: {
+            readonly userId: string;
+            readonly tokenId: string;
+        }) => Effect.Effect<import("kysely").DeleteResult[], import("@withstudiocms/kysely").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+        /**
+         * Verifies an API token and retrieves associated user information.
+         *
+         * @param key - The API token to verify.
+         * @returns An Effect that resolves to user information if the token is valid, or false if invalid.
+         */
+        verify: (key: string) => Effect.Effect<false | {
+            userId: string;
+            key: string;
+            rank: "owner" | "admin" | "editor" | "visitor" | "unknown";
+        }, import("@withstudiocms/kysely").DBCallbackFailure | import("@withstudiocms/kysely/core/errors").DatabaseError, never>;
+    };
+}, import("effect/ConfigError").ConfigError, DBClientLive>;
+export default SDKRestAPIModule;