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

package/dist/modules/util/generators.d.ts

@@ -0,0 +1,83 @@
+import { Effect } from '@withstudiocms/effect';
+import type { JwtVerificationResult } from '../../types.js';
+declare const GeneratorError_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: "GeneratorError";
+} & Readonly<A>;
+/**
+ * Represents errors that occur during generator operations.
+ */
+export declare class GeneratorError extends GeneratorError_base<{
+    cause: unknown;
+}> {
+}
+/**
+ * A helper function to wrap generator operations in an Effect with error handling.
+ *
+ * @param _try - A function that performs the generator operation.
+ * @returns An Effect that either yields the result of the operation or fails with a GeneratorError.
+ */
+export declare const useGeneratorError: <A>(_try: () => A) => Effect.Effect<A, GeneratorError, never>;
+/**
+ * SDKGenerators
+ *
+ * Effect generator that builds a collection of utility functions used across the SDK.
+ *
+ * This generator:
+ * - Reads the CMS encryption key from configuration (CMS_ENCRYPTION_KEY). The key's value is kept redacted for
+ *   safety in logs and debug output; the generator uses the redacted value for cryptographic operations where needed.
+ * - Exposes utilities for creating random IDs, secure passwords, issuing JWTs for users, and verifying JWTs.
+ *
+ * Exposed utilities:
+ * - generateRandomIDNumber(length: number): number
+ *   - Generates a numeric identifier of the specified length.
+ *   - Uses Math.random() and therefore is suitable for non-cryptographic identifiers.
+ *
+ * - generateRandomPassword(length: number): string
+ *   - Produces a password of the requested length using the character set
+ *     "A-Z a-z 0-9".
+ *   - Uses crypto.getRandomValues and rejection sampling to avoid modulo bias, providing cryptographically
+ *     strong random selection from the character set.
+ *
+ * - generateToken(userId: string, noExpire?: boolean): string
+ *   - Creates a signed JSON Web Token for the supplied userId.
+ *   - By default the token is time-limited (expires in a short timeframe — implementation uses a 3 hour default).
+ *     Passing `noExpire = true` will produce a token without the automatic expiry.
+ *   - Token signing uses the CMS encryption key (redacted) via the SDK's internal JWT generation routine.
+ *
+ * - testToken(token: string): Effect.Effect<JwtVerificationResult, GeneratorError, never>
+ *   - Validates the provided JWT using the CMS encryption key.
+ *   - Verification performs:
+ *     - header algorithm check (expects HS256),
+ *     - expiration check (tokens with exp in the past are rejected),
+ *     - signature verification (HMAC SHA-256 using the configured secret).
+ *   - Returns a JwtVerificationResult indicating whether the token is valid and, if so, the userId extracted from the token.
+ *
+ * Error handling and effects:
+ * - Many operations are wrapped with the generator's error handling helpers and may fail with GeneratorError when
+ *   JSON parsing, cryptographic operations, or other wrapped computations error.
+ * - Sensitive values (CMS encryption key) are handled in redacted form to avoid accidental exposure.
+ *
+ * Security notes:
+ * - generateRandomPassword uses cryptographically secure randomness; generateRandomIDNumber does not and should not
+ *   be used where cryptographic unpredictability is required.
+ * - Tokens are signed and validated using HMAC-SHA256 (HS256). Ensure the configured CMS_ENCRYPTION_KEY is strong and
+ *   kept secret.
+ *
+ * Returns:
+ * - An object containing the four utilities: { generateRandomIDNumber, generateRandomPassword, generateToken, testToken }.
+ *
+ * Example:
+ * @example
+ * const sdk = yield* SDKGenerators;
+ * const token = yield* sdk.generateToken('user-123');
+ * const result = yield* sdk.testToken(token);
+ *
+ * @throws {GeneratorError} if any underlying generator-wrapped operation (parsing, crypto, config retrieval) fails.
+ */
+export declare const SDKGenerators: Effect.Effect<{
+    generateRandomIDNumber: (length: number) => Effect.Effect<number, GeneratorError, never>;
+    generateRandomPassword: (length: number) => Effect.Effect<string, GeneratorError, never>;
+    generateToken: (userId: string, noExpire?: boolean | undefined) => Effect.Effect<string, GeneratorError, never>;
+    testToken: (token: string) => Effect.Effect<JwtVerificationResult, GeneratorError, never>;
+}, import("effect/ConfigError").ConfigError, never>;
+export {};

package/dist/modules/util/generators.js

@@ -0,0 +1,106 @@
+import * as crypto from "node:crypto";
+import { Config, Data, Effect, Redacted } from "@withstudiocms/effect";
+class GeneratorError extends Data.TaggedError("GeneratorError") {
+}
+const useGeneratorError = (_try) => Effect.try({
+  try: _try,
+  catch: (error) => new GeneratorError({ cause: error })
+});
+const SDKGenerators = Effect.gen(function* () {
+  const redactedCMSEncryptionKey = yield* Config.redacted("CMS_ENCRYPTION_KEY");
+  const cmsEncryptionKey = Redacted.value(redactedCMSEncryptionKey);
+  const base64UrlEncode = (input) => Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  const base64UrlDecode = (input) => {
+    let newInput = input.replace(/-/g, "+").replace(/_/g, "/");
+    while (newInput.length % 4 !== 0) {
+      newInput += "=";
+    }
+    return Buffer.from(newInput, "base64").toString();
+  };
+  const generateJwt = Effect.fn(
+    (secret, payload, noExpire) => useGeneratorError(() => {
+      const header = { alg: "HS256", typ: "JWT" };
+      const currentDate = /* @__PURE__ */ new Date();
+      const thirtyYearsFromToday = Math.floor(
+        currentDate.setFullYear(currentDate.getFullYear() + 30) / 1e3
+      );
+      const exp = noExpire ? thirtyYearsFromToday : Math.floor(Date.now() / 1e3) + 86400;
+      const payloadObj = {
+        ...payload,
+        iat: Math.floor(Date.now() / 1e3),
+        // Corrected iat
+        exp
+      };
+      const encodedHeader = base64UrlEncode(JSON.stringify(header));
+      const encodedPayload = base64UrlEncode(JSON.stringify(payloadObj));
+      const signatureInput = `${encodedHeader}.${encodedPayload}`;
+      const signature = Buffer.from(
+        crypto.createHmac("sha256", secret + secret).update(signatureInput).digest()
+      ).toString("base64url");
+      return `${encodedHeader}.${encodedPayload}.${signature}`;
+    })
+  );
+  const verifyJwt = (token, secret) => Effect.gen(function* () {
+    const [encodedHeader, encodedPayload, encodedSignature] = token.split(".");
+    if (!encodedHeader || !encodedPayload || !encodedSignature) {
+      yield* Effect.logDebug("Invalid token format");
+      return { isValid: false };
+    }
+    const [header, payload] = yield* Effect.all([
+      useGeneratorError(() => JSON.parse(base64UrlDecode(encodedHeader))),
+      useGeneratorError(() => JSON.parse(base64UrlDecode(encodedPayload)))
+    ]);
+    if (header.alg !== "HS256") {
+      yield* Effect.logDebug("Invalid algorithm");
+      return { isValid: false };
+    }
+    const currentTime = Math.floor(Date.now() / 1e3);
+    if (payload.exp && currentTime > payload.exp) {
+      yield* Effect.logDebug("Token has expired");
+      return { isValid: false };
+    }
+    const signatureInput = `${encodedHeader}.${encodedPayload}`;
+    const generatedSignature = yield* useGeneratorError(() => {
+      return Buffer.from(
+        crypto.createHmac("sha256", secret + secret).update(signatureInput).digest()
+      ).toString("base64url");
+    });
+    if (generatedSignature !== encodedSignature) {
+      yield* Effect.logDebug("Invalid signature");
+      return { isValid: false };
+    }
+    return { isValid: true, userId: payload.userId };
+  });
+  const generateRandomIDNumber = Effect.fn(
+    (length) => useGeneratorError(() => Math.floor(Math.random() * 10 ** length))
+  );
+  const generateRandomPassword = Effect.fn(
+    (length) => useGeneratorError(() => {
+      const characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+      let password = "";
+      const maxValidValue = Math.floor((2 ** 32 - 1) / characters.length) * characters.length;
+      while (password.length < length) {
+        const n = crypto.getRandomValues(new Uint32Array(1))[0];
+        if (n < maxValidValue) {
+          password += characters[n % characters.length];
+        }
+      }
+      return password;
+    })
+  );
+  const generateToken = Effect.fn(
+    (userId, noExpire) => generateJwt(cmsEncryptionKey, { userId }, noExpire)
+  );
+  const testToken = Effect.fn((token) => verifyJwt(token, cmsEncryptionKey));
+  return {
+    generateRandomIDNumber,
+    generateRandomPassword,
+    generateToken,
+    testToken
+  };
+});
+export {
+  GeneratorError,
+  SDKGenerators,
+  useGeneratorError
+};

package/dist/modules/util/getFromNPM.d.ts

@@ -0,0 +1,191 @@
+import { Effect, Schema } from '@withstudiocms/effect';
+import { CacheService } from '../../cache.js';
+declare const NpmRegistryResponseSchema_base: Schema.Class<NpmRegistryResponseSchema, {
+    _id: typeof Schema.String;
+    _integrity: typeof Schema.String;
+    _npmUser: Schema.Struct<{
+        name: typeof Schema.String;
+        email: typeof Schema.String;
+        trustedPublisher: Schema.Struct<{
+            id: typeof Schema.String;
+            oidcConfigId: typeof Schema.String;
+        }>;
+    }>;
+    maintainers: Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        email: typeof Schema.String;
+    }>>;
+    name: typeof Schema.String;
+    version: typeof Schema.String;
+    description: typeof Schema.String;
+    license: typeof Schema.String;
+    author: Schema.optional<Schema.Struct<{
+        name: typeof Schema.String;
+        url: typeof Schema.String;
+    }>>;
+    repository: Schema.optional<Schema.Struct<{
+        type: typeof Schema.String;
+        url: typeof Schema.String;
+        directory: Schema.optional<typeof Schema.String>;
+    }>>;
+    contributors: Schema.optional<Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        url: Schema.optional<typeof Schema.String>;
+    }>>>;
+    keywords: Schema.Array$<typeof Schema.String>;
+    homepage: Schema.optional<typeof Schema.String>;
+    publishConfig: Schema.optional<Schema.Struct<{
+        access: typeof Schema.String;
+        provenance: typeof Schema.Boolean;
+    }>>;
+    sideEffects: Schema.optional<typeof Schema.Boolean>;
+}, Schema.Struct.Encoded<{
+    _id: typeof Schema.String;
+    _integrity: typeof Schema.String;
+    _npmUser: Schema.Struct<{
+        name: typeof Schema.String;
+        email: typeof Schema.String;
+        trustedPublisher: Schema.Struct<{
+            id: typeof Schema.String;
+            oidcConfigId: typeof Schema.String;
+        }>;
+    }>;
+    maintainers: Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        email: typeof Schema.String;
+    }>>;
+    name: typeof Schema.String;
+    version: typeof Schema.String;
+    description: typeof Schema.String;
+    license: typeof Schema.String;
+    author: Schema.optional<Schema.Struct<{
+        name: typeof Schema.String;
+        url: typeof Schema.String;
+    }>>;
+    repository: Schema.optional<Schema.Struct<{
+        type: typeof Schema.String;
+        url: typeof Schema.String;
+        directory: Schema.optional<typeof Schema.String>;
+    }>>;
+    contributors: Schema.optional<Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        url: Schema.optional<typeof Schema.String>;
+    }>>>;
+    keywords: Schema.Array$<typeof Schema.String>;
+    homepage: Schema.optional<typeof Schema.String>;
+    publishConfig: Schema.optional<Schema.Struct<{
+        access: typeof Schema.String;
+        provenance: typeof Schema.Boolean;
+    }>>;
+    sideEffects: Schema.optional<typeof Schema.Boolean>;
+}>, never, {
+    readonly name: string;
+} & {
+    readonly description: string;
+} & {
+    readonly _id: string;
+} & {
+    readonly _integrity: string;
+} & {
+    readonly version: string;
+} & {
+    readonly license: string;
+} & {
+    readonly _npmUser: {
+        readonly name: string;
+        readonly email: string;
+        readonly trustedPublisher: {
+            readonly id: string;
+            readonly oidcConfigId: string;
+        };
+    };
+} & {
+    readonly maintainers: readonly {
+        readonly name: string;
+        readonly email: string;
+    }[];
+} & {
+    readonly author?: {
+        readonly name: string;
+        readonly url: string;
+    } | undefined;
+} & {
+    readonly repository?: {
+        readonly type: string;
+        readonly url: string;
+        readonly directory?: string | undefined;
+    } | undefined;
+} & {
+    readonly contributors?: readonly {
+        readonly name: string;
+        readonly url?: string | undefined;
+    }[] | undefined;
+} & {
+    readonly keywords: readonly string[];
+} & {
+    readonly homepage?: string | undefined;
+} & {
+    readonly publishConfig?: {
+        readonly access: string;
+        readonly provenance: boolean;
+    } | undefined;
+} & {
+    readonly sideEffects?: boolean | undefined;
+}, {}, {}>;
+/**
+ * Represents the shape of an npm registry document for a specific package version.
+ *
+ * This class models the JSON structure returned by the npm registry for a published
+ * package version. It includes metadata about the package (name, version, description,
+ * license), publisher/maintainer information, repository and publish configuration,
+ * and other auxiliary fields commonly present on the npm registry.
+ *
+ * @remarks
+ * The shape mirrors common fields returned by the npm registry and is suitable for
+ * validating or typing responses when fetching package metadata (for example via
+ * the registry REST API). Optional fields reflect that not all packages supply every
+ * piece of metadata.
+ *
+ * @public
+ */
+export declare class NpmRegistryResponseSchema extends NpmRegistryResponseSchema_base {
+}
+/**
+ * Helper to process and validate the HTTP response from the NPM registry.
+ */
+export declare const parseNpmRegistryResponse: (response: Response) => Effect.Effect<NpmRegistryResponseSchema, import("effect/Cause").UnknownException | import("effect/ParseResult").ParseError, never>;
+/**
+ * Cache key for NPM package data.
+ */
+export declare const cacheKey: (name: string, version: string) => string;
+/**
+ * Cache options for NPM package data.
+ */
+export declare const cacheOpts: {
+    tags: string[];
+};
+/**
+ * An Effect service for retrieving the version of an NPM package from the NPM registry.
+ *
+ * @remarks
+ * This service uses an HTTP client with retry logic to fetch the version information
+ * for a given package and version (defaulting to 'latest') from the NPM registry.
+ *
+ * @example
+ * ```typescript
+ * const version = await GetVersionFromNPM.get('react');
+ * ```
+ *
+ * @method get
+ * @param pkg - The name of the NPM package.
+ * @param ver - The version tag or number (defaults to 'latest').
+ * @returns An Effect that resolves to the version string of the specified package.
+ */
+export declare const GetFromNPM: Effect.Effect<{
+    getVersion: (pkg: string, ver?: string | undefined) => Effect.Effect<{
+        version: string;
+        lastCacheUpdate: Date;
+    }, import("effect/Cause").UnknownException | Error | import("effect/ParseResult").ParseError, never>;
+    getDataFromNPM: (pkg: string, ver?: string | undefined) => Effect.Effect<NpmRegistryResponseSchema, import("effect/Cause").UnknownException | Error | import("effect/ParseResult").ParseError, never>;
+}, never, CacheService>;
+export {};

package/dist/modules/util/getFromNPM.js

@@ -0,0 +1,100 @@
+import { Effect, HTTPClient, Schema } from "@withstudiocms/effect";
+import { CacheService } from "../../cache.js";
+import { cacheKeyGetters, cacheTags } from "../../consts.js";
+class NpmRegistryResponseSchema extends Schema.Class(
+  "NpmRegistryResponseSchema"
+)({
+  _id: Schema.String,
+  _integrity: Schema.String,
+  _npmUser: Schema.Struct({
+    name: Schema.String,
+    email: Schema.String,
+    trustedPublisher: Schema.Struct({
+      id: Schema.String,
+      oidcConfigId: Schema.String
+    })
+  }),
+  maintainers: Schema.Array(
+    Schema.Struct({
+      name: Schema.String,
+      email: Schema.String
+    })
+  ),
+  name: Schema.String,
+  version: Schema.String,
+  description: Schema.String,
+  license: Schema.String,
+  author: Schema.optional(
+    Schema.Struct({
+      name: Schema.String,
+      url: Schema.String
+    })
+  ),
+  repository: Schema.optional(
+    Schema.Struct({
+      type: Schema.String,
+      url: Schema.String,
+      directory: Schema.optional(Schema.String)
+    })
+  ),
+  contributors: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        name: Schema.String,
+        url: Schema.optional(Schema.String)
+      })
+    )
+  ),
+  keywords: Schema.Array(Schema.String),
+  homepage: Schema.optional(Schema.String),
+  publishConfig: Schema.optional(
+    Schema.Struct({
+      access: Schema.String,
+      provenance: Schema.Boolean
+    })
+  ),
+  sideEffects: Schema.optional(Schema.Boolean)
+}) {
+}
+const parseNpmRegistryResponse = Effect.fn(function* (response) {
+  const data = yield* Effect.tryPromise(() => response.json());
+  return yield* Schema.decodeUnknown(NpmRegistryResponseSchema)(data);
+});
+const cacheKey = cacheKeyGetters.npmPackage;
+const cacheOpts = { tags: cacheTags.npmPackage };
+const GetFromNPM = Effect.gen(function* () {
+  const [{ memoize, getCacheStatus }] = yield* Effect.all([CacheService]);
+  const effectFetch = Effect.fn(
+    (url) => Effect.tryPromise({
+      try: () => fetch(url),
+      catch: (error) => new Error(`Failed to fetch NPM package data: ${String(error)}`)
+    })
+  );
+  const _remapCacheStatusData = (status) => status ? status.lastUpdatedAt : /* @__PURE__ */ new Date();
+  const _remapData = (pkg, srcVer) => ({ version }) => Effect.all({
+    version: Effect.succeed(version),
+    lastCacheUpdate: getCacheStatus(cacheKey(pkg, srcVer || "latest")).pipe(
+      Effect.map(_remapCacheStatusData)
+    )
+  });
+  const getDataFromNPM = Effect.fn(
+    (pkg, ver) => memoize(
+      cacheKey(pkg, ver || "latest"),
+      effectFetch(`https://registry.npmjs.org/${pkg}/${ver || "latest"}`).pipe(
+        Effect.flatMap(parseNpmRegistryResponse)
+      ),
+      cacheOpts
+    )
+  );
+  const getVersion = Effect.fn(
+    (pkg, ver) => getDataFromNPM(pkg, ver).pipe(Effect.flatMap(_remapData(pkg, ver)))
+  );
+  return { getVersion, getDataFromNPM };
+}).pipe(Effect.provide(HTTPClient.Default));
+export {
+  GetFromNPM,
+  NpmRegistryResponseSchema,
+  cacheKey,
+  cacheOpts,
+  parseNpmRegistryResponse
+};