@sitecore-content-sdk/core 0.2.0-beta.2 → 0.2.0-beta.21

package/types/site/graphql-robots-service.d.ts

@@ -1,4 +1,4 @@
-import { GraphQLClient } from '../client';
+import { FetchOptions, GraphQLClient } from '../client';
 import { GraphQLRequestClientFactory } from '../graphql-request-client';
 export type GraphQLRobotsServiceConfig = {
     /**
@@ -35,10 +35,11 @@ export declare class GraphQLRobotsService {
     protected get query(): string;
     /**
      * Fetch a data of robots.txt from API
+     * @param {FetchOptions} fetchOptions - The fetch options to be used for the request.
      * @returns text of robots.txt
      * @throws {Error} if the siteName is empty.
      */
-    fetchRobots(): Promise<string>;
+    fetchRobots(fetchOptions?: FetchOptions): Promise<string>;
     /**
      * Gets a GraphQL client that can make requests to the API. Uses graphql-request as the default
      * library for fetching graphql data (@see GraphQLRequestClient). Override this method if you

package/types/tools/auth/encryption.d.ts

@@ -0,0 +1,34 @@
+import { EncryptedPayload } from './models';
+/**
+ * Encrypts plaintext using AES-256-GCM for a given tenant.
+ * @param {string} plaintext
+ * @param {string} tenantId
+ */
+export declare let encryptData: typeof _encryptData;
+/**
+ * Decrypts encrypted payload using AES-256-GCM for a specific tenant.
+ * If key is corrupted or invalid, optionally clears both key and tenant data.
+ * @param {EncryptedPayload} payload
+ * @param {string} tenantId
+ * @param {string} cleanupOnFailure
+ */
+export declare let decryptData: typeof _decryptData;
+/**
+ * Deletes the encryption key for a tenant (useful for cleanup).
+ * @param {string} tenantId
+ */
+export declare let deleteKey: typeof _deleteKey;
+export declare const unitMocks: {
+    encryptData: typeof _encryptData;
+    decryptData: typeof _decryptData;
+    deleteKey: typeof _deleteKey;
+};
+/**
+ * Generates or retrieves a 32-byte AES key for a specific tenant.
+ * @param {string} tenantId
+ */
+export declare function getKey(tenantId: string): Promise<Buffer>;
+declare function _encryptData(plaintext: string, tenantId: string): Promise<EncryptedPayload>;
+declare function _decryptData(payload: EncryptedPayload, tenantId: string, cleanupOnFailure?: boolean): Promise<string | null>;
+declare function _deleteKey(tenantId: string): Promise<void>;
+export {};

package/types/tools/auth/fetcher.d.ts

@@ -0,0 +1,13 @@
+export declare const unitMocks: {
+    sendPostRequest: typeof _sendPostRequest;
+};
+/**
+ * Performs a POST request with application/x-www-form-urlencoded headers.
+ * @param {string} url - The endpoint to post to.
+ * @param { URLSearchParams} params - A URLSearchParams instance representing the body.
+ * @returns Parsed JSON response.
+ * @throws Error if response is not OK.
+ */
+export declare let sendPostRequest: typeof _sendPostRequest;
+declare function _sendPostRequest<T>(url: string, params: URLSearchParams, throwOnError?: boolean): Promise<T>;
+export {};

package/types/tools/auth/flow.d.ts

@@ -0,0 +1,40 @@
+import { DeviceAuthRequest, DeviceAuthResponse, DeviceTokenPollRequest, TenantArgs, AuthResponse } from './models';
+/**
+ * Performs the OAuth 2.0 client credentials flow to obtain a JWT access token
+ * from the Sitecore Identity Provider using the provided client credentials.
+ * @param {TenantArgs} params - Parameters including clientId, clientSecret, organizationId, tenantId, audience, authority, and baseUrl.
+ * @returns A Promise that resolves to the access token response (including access token, token type, expiry, etc.)
+ * @throws Will log and exit the process if the request fails or returns a non-OK status
+ */
+export declare let clientCredentialsFlow: typeof _clientCredentialsFlow;
+/**
+ * Initiates the OAuth 2.0 Device Authorization flow by requesting a device and user code.
+ * This flow is typically used by devices or CLI apps that cannot input credentials directly.
+ * @param {DeviceAuthRequest} params - Parameters including clientId, audience, authority, and baseUrl.
+ * @returns {Promise<DeviceAuthResponse>} A promise resolving to device authorization metadata needed for polling.
+ * @throws {Error} If the device authorization request fails or returns an error response.
+ */
+export declare let startDeviceAuthFlow: typeof _startDeviceAuthFlow;
+/**
+ * Polls the OAuth 2.0 device token endpoint to retrieve the access token once the user has authorized the device.
+ * This is typically used to continue the device authorization process after a user enters a code on a browser.
+ * @param {DeviceTokenPollRequest} params - Parameters for polling including clientId, deviceCode, interval, and authority.
+ * @returns {Promise<any>} A promise resolving to the device token response including access token and refresh token.
+ * @throws {Error} If polling fails or exceeds the timeout period.
+ */
+export declare let pollForDeviceToken: typeof _pollForDeviceToken;
+export declare const unitMocks: {
+    clientCredentialsFlow: typeof _clientCredentialsFlow;
+    startDeviceAuthFlow: typeof _startDeviceAuthFlow;
+    pollForDeviceToken: typeof _pollForDeviceToken;
+};
+declare function _clientCredentialsFlow({ clientId, clientSecret, organizationId, tenantId, audience, authority, baseUrl, }: TenantArgs): Promise<{
+    data: AuthResponse;
+    tokenOrgId: any;
+    tokenTenantId: any;
+    tokenTenantName: any;
+    accessToken: string;
+}>;
+export declare function _startDeviceAuthFlow({ clientId, audience, authority, baseUrl, }: DeviceAuthRequest): Promise<DeviceAuthResponse>;
+export declare function _pollForDeviceToken({ clientId, device_code, interval, authority, }: DeviceTokenPollRequest): Promise<AuthResponse>;
+export {};

package/types/tools/auth/index.d.ts

@@ -0,0 +1,5 @@
+export { clientCredentialsFlow, startDeviceAuthFlow, pollForDeviceToken } from './flow';
+export { renewClientToken, validateAndRenewAuthIfExpired, validateAuthInfo, getRefreshAccessToken, } from './renewal';
+export { getActiveTenant, setActiveTenant, clearActiveTenant } from './tenant-state';
+export { writeTenantAuthInfo, readTenantAuthInfo, deleteTenantAuthInfo, readTenantInfo, getAllTenantsInfo, writeTenantInfo, } from './tenant-store';
+export { encryptData, decryptData, deleteKey } from './encryption';

package/types/tools/auth/models.d.ts

@@ -0,0 +1,233 @@
+/**
+ * CLI arguments used for authentication and tenant identification.
+ */
+export interface TenantArgs {
+    /**
+     * OAuth2 client ID used to identify the application
+     */
+    clientId: string;
+    /**
+     * Client secret used for client credentials flow
+     */
+    clientSecret?: string;
+    /**
+     * Organization ID associated with the tenant
+     */
+    organizationId?: string;
+    /**
+     * Tenant ID used for scoping the login
+     */
+    tenantId?: string;
+    /**
+     * OAuth2 audience (e.g., API base URL the token is intended for)
+     */
+    audience?: string;
+    /**
+     * Auth authority/issuer URL (e.g., Sitecore identity endpoint)
+     */
+    authority?: string;
+    /**
+     * Base URL for the target Sitecore Content Management API
+     */
+    baseUrl?: string;
+}
+export interface TenantSettings {
+    /**
+     * Currently active tenant ID tracked by the CLI
+     */
+    activeTenant?: string;
+}
+/**
+ * Auth configuration stored per tenant for accessing Sitecore APIs.
+ */
+export interface TenantAuthInfo {
+    /**
+     * Access token issued by the identity provider
+     */
+    access_token: string;
+    /**
+     * Token expiration duration in seconds
+     */
+    expires_in: number;
+    /**
+     * Exact ISO timestamp when the token expires
+     */
+    expires_at: string;
+    /**
+     * Secret used for client credentials flow and re-authenticate
+     */
+    clientSecret?: string;
+    refresh_token?: string;
+}
+/**
+ * Public metadata for a known tenant.
+ */
+export interface TenantInfo {
+    /**
+     * Unique ID of the tenant
+     */
+    tenantId: string;
+    /**
+     *  Human-readable name of the tenant
+     */
+    tenantName: string;
+    /**
+     * Organization ID the tenant belongs to
+     */
+    organizationId: string;
+    /**
+     * Client ID associated with this tenant's authentication
+     */
+    clientId: string;
+    /**
+     * OAuth2 audience (e.g., API base URL the token is intended for)
+     */
+    audience: string;
+    /**
+     * Auth authority/issuer URL (e.g., Sitecore identity endpoint)
+     */
+    authority: string;
+    /**
+     * Base URL for the target Sitecore Content Management API
+     */
+    baseUrl: string;
+}
+export type EncryptedPayload = {
+    iv: string;
+    /**
+     * Authentication tag for integrity verification
+     */
+    authTag: string;
+    /**
+     * Base64-encoded encrypted data
+     */
+    encryptedData: string;
+};
+/**
+ * Input parameters for exchanging a refresh token for a new access token.
+ */
+export interface RefreshTokenRequest {
+    /**
+     * OAuth 2.0 client identifier.
+     */
+    clientId: string;
+    /**
+     * Refresh token previously issued by the authorization server.
+     */
+    refreshToken: string;
+    /**
+     * Tenant identifier to bind the request to a specific tenant context.
+     */
+    tenantId: string;
+    /**
+     * Organization identifier for multi-tenant authorization scope.
+     */
+    organizationId: string;
+    /**
+     * Optional OAuth 2.0 authority endpoint (token issuer URL).
+     * Defaults to the Sitecore standard authority if not provided.
+     */
+    authority?: string;
+}
+/**
+ * Input parameters for initiating the OAuth 2.0 Device Authorization flow.
+ */
+export interface DeviceAuthRequest {
+    /**
+     * OAuth 2.0 client identifier.
+     */
+    clientId: string;
+    /**
+     * The intended recipient of the token (usually your protected resource or API).
+     */
+    audience: string;
+    /**
+     * OAuth 2.0 authority URL (token issuer).
+     */
+    authority: string;
+    /**
+     * Base URL for your API, used to build custom claims or context if needed.
+     */
+    baseUrl: string;
+}
+/**
+ * Response structure returned after initiating the device authorization flow.
+ */
+export interface DeviceAuthResponse {
+    /**
+     * Code the device will use to poll the token endpoint.
+     */
+    device_code: string;
+    /**
+     * Code shown to the user for manual input during verification.
+     */
+    user_code: string;
+    /**
+     * URI where the user should go to complete authentication.
+     */
+    verification_uri: string;
+    /**
+     * Optional URI that includes the user code, allowing for a streamlined login experience.
+     */
+    verification_uri_complete?: string;
+    /**
+     * Time (in seconds) until the device code expires.
+     */
+    expires_in: number;
+    /**
+     * Recommended polling interval (in seconds) for token requests.
+     */
+    interval: number;
+}
+/**
+ * Input parameters for polling the OAuth 2.0 device token endpoint.
+ */
+export interface DeviceTokenPollRequest {
+    /**
+     * OAuth 2.0 client identifier.
+     */
+    clientId: string;
+    /**
+     * Device code previously obtained from the device authorization flow.
+     */
+    device_code: string;
+    /**
+     * Optional polling interval in seconds. If not provided, a default is used.
+     */
+    interval?: number;
+    /**
+     * Optional OAuth 2.0 authority endpoint for token polling.
+     */
+    authority?: string;
+}
+/**
+ * Represents the raw OAuth token response returned by the authorization server.
+ * This includes the access token, refresh token, and optional ID token and scope.
+ */
+export interface TokenResponse {
+    /** The access token used for authenticating API requests */
+    access_token: string;
+    /** The refresh token used to obtain a new access token when it expires */
+    refresh_token: string;
+    /** The number of seconds until the access token expires */
+    expires_in: number;
+    /** The type of token issued, typically "Bearer" */
+    token_type: string;
+    /** An optional ID token containing user identity claims (usually JWT) */
+    id_token?: string;
+    /** The scopes granted for the access token, space-delimited */
+    scope?: string;
+}
+/**
+ * Represents the application-specific token response returned by `_getRefreshAccessToken`.
+ * In addition to the raw OAuth tokens, it includes the decoded `tenantName` for convenience.
+ */
+export interface RefreshAccessTokenResponse extends TokenResponse {
+    /** The tenant name extracted from the decoded access token payload */
+    tenantName?: string;
+}
+export interface AuthResponse {
+    [key: string]: any;
+    access_token: string;
+    expires_in: number;
+}

package/types/tools/auth/renewal.d.ts

@@ -0,0 +1,36 @@
+import { RefreshAccessTokenResponse, RefreshTokenRequest, TenantAuthInfo, TenantInfo } from './models';
+/**
+ * Requests a new access token using the OAuth 2.0 refresh token grant type.
+ * This is used to "upgrade" an initial device flow token by including tenant-specific context.
+ * @param {RefreshTokenRequest} options - Configuration for the refresh token request.
+ * @returns {Promise<any>} A promise that resolves to the refreshed token data including tenant context.
+ * @throws {Error} If the token request fails or returns an error response.
+ */
+export declare let getRefreshAccessToken: typeof _getRefreshAccessToken;
+export declare const unitMocks: {
+    getRefreshAccessToken: typeof _getRefreshAccessToken;
+};
+/**
+ * Validates whether a given auth config is still valid (i.e., not expired).
+ * @param {TenantAuth} authInfo - The tenant auth configuration.
+ * @returns True if the token is still valid, false if expired.
+ */
+export declare function validateAuthInfo(authInfo: TenantAuthInfo): boolean;
+/**
+ * Renews the token for a given tenant using stored credentials.
+ * @param {TenantAuth} authInfo - Current authentication info for the tenant.
+ * @param {TenantInfo} tenantInfo - Public metadata about the tenant (e.g., clientId).
+ * @returns {Promise<void>} resolving when the token is successfully renewed.
+ * @throws If credentials are missing or renewal fails.
+ */
+export declare function renewClientToken(authInfo: TenantAuthInfo, tenantInfo: TenantInfo): Promise<void>;
+/**
+ * Ensures a valid token exists, renews it if expired.
+ * @returns {Promise<{ tenantId: string } | null>} returns tenant context if successful, otherwise null.
+ * @throws If renewal fails or credentials are missing.
+ */
+export declare function validateAndRenewAuthIfExpired(): Promise<{
+    tenantId: string;
+} | null>;
+declare function _getRefreshAccessToken({ clientId, refreshToken, tenantId, organizationId, authority, }: RefreshTokenRequest): Promise<RefreshAccessTokenResponse>;
+export {};

package/types/tools/auth/tenant-state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Gets the ID of the currently active tenant from settings.json.
+ * @returns The active tenant ID if present, otherwise null.
+ */
+export declare let getActiveTenant: typeof _getActiveTenant;
+/**
+ * Clears the currently active tenant from settings.json by deleting the file.
+ */
+export declare let clearActiveTenant: typeof _clearActiveTenant;
+export declare const unitMocks: {
+    clearActiveTenant: typeof _clearActiveTenant;
+    getActiveTenant: typeof _getActiveTenant;
+};
+declare function _getActiveTenant(): string | null;
+/**
+ * Sets the currently active tenant by writing to settings.json.
+ * @param {string} tenantId - The tenant ID to set as active.
+ */
+export declare function setActiveTenant(tenantId: string): void;
+declare function _clearActiveTenant(): void;
+export {};

package/types/tools/auth/tenant-store.d.ts

@@ -0,0 +1,63 @@
+import { TenantAuthInfo, TenantInfo } from './models';
+/**
+ * Decodes a JWT without verifying its signature.
+ * @param {string} token - The access token string.
+ * @returns Decoded payload object or null if invalid.
+ */
+export declare let decodeJwtPayload: typeof _decodeJwtPayload;
+/**
+ * Write the authentication configuration for a tenant.
+ * @param {string} tenantId - The tenant ID.
+ * @param {TenantAuth} authInfo - The tenant's auth data.
+ */
+export declare let writeTenantAuthInfo: typeof _writeTenantAuthInfo;
+/**
+ * Read the authentication configuration for a tenant.
+ * @param {string} tenantId - The tenant ID.
+ * @returns Parsed auth config or null if not found or failed to read.
+ */
+export declare let readTenantAuthInfo: typeof _readTenantAuthInfo;
+/**
+ * Write the public metadata information for a tenant.
+ * @param {TenantInfo} info - The tenant info object.
+ */
+export declare let writeTenantInfo: typeof _writeTenantInfo;
+/**
+ * Read the public metadata information for a tenant.
+ * @param {string} tenantId - The tenant ID.
+ * @returns Parsed tenant info or null if not found or failed to read.
+ */
+export declare let readTenantInfo: typeof _readTenantInfo;
+/**
+ * Deletes the stored auth.json file for the given tenant.
+ * @param {string} tenantId - The tenant ID.
+ */
+export declare let deleteTenantAuthInfo: typeof _deleteTenantAuthInfo;
+/**
+ * Scans the CLI root directory and returns all valid tenant infos.
+ * @returns A list of TenantInfo objects found in {tenant-id}/info.json files.
+ */
+export declare let getAllTenantsInfo: typeof _getAllTenantsInfo;
+export declare const unitMocks: {
+    decodeJwtPayload: typeof _decodeJwtPayload;
+    writeTenantAuthInfo: typeof _writeTenantAuthInfo;
+    readTenantAuthInfo: typeof _readTenantAuthInfo;
+    writeTenantInfo: typeof _writeTenantInfo;
+    readTenantInfo: typeof _readTenantInfo;
+    deleteTenantAuthInfo: typeof _deleteTenantAuthInfo;
+    getAllTenantsInfo: typeof _getAllTenantsInfo;
+};
+/**
+ * Get the full path to the tenant-specific folder.
+ * @param {string} tenantId - The tenant ID.
+ * @returns The absolute path to the tenant directory.
+ */
+export declare function getTenantPath(tenantId: string): string;
+declare function _writeTenantAuthInfo(tenantId: string, authInfo: TenantAuthInfo): Promise<void>;
+declare function _readTenantAuthInfo(tenantId: string): Promise<TenantAuthInfo | null>;
+declare function _writeTenantInfo(info: TenantInfo): Promise<void>;
+declare function _readTenantInfo(tenantId: string): Promise<TenantInfo | null>;
+declare function _deleteTenantAuthInfo(tenantId: string): Promise<void>;
+declare function _getAllTenantsInfo(): TenantInfo[];
+declare function _decodeJwtPayload(token: string): Record<string, any> | null;
+export {};

package/types/tools/index.d.ts

@@ -2,3 +2,6 @@ export { generateSites, GenerateSitesConfig } from './generateSites';
 export { generateMetadata } from './generateMetadata';
 export { scaffoldComponent } from './scaffold';
 export * from './templating';
+export * from './auth/models';
+import * as auth from './auth';
+export { auth };

package/types/utils/normalize-url.d.ts

@@ -0,0 +1 @@
+export declare const normalizeUrl: (url: string) => string;

package/dist/cjs/data-fetcher.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResponseError = void 0;
-exports.fetchData = fetchData;
-const utils_1 = require("./utils/utils");
-class ResponseError extends Error {
-    constructor(message, response) {
-        super(message);
-        Object.setPrototypeOf(this, ResponseError.prototype);
-        this.response = response;
-    }
-}
-exports.ResponseError = ResponseError;
-/**
- * @param {string} url the URL to request; may include query string
- * @param {HttpDataFetcher<T> | NativeDataFetcherFunction<T>} fetcher the fetcher to use to perform the request
- * @param {ParsedUrlQueryInput} params the query string parameters to send with the request
- */
-async function fetchData(url, fetcher, params = {}) {
-    const response = await fetcher((0, utils_1.resolveUrl)(url, params));
-    return response.data;
-}

package/dist/esm/data-fetcher.js

@@ -1,17 +0,0 @@
-import { resolveUrl } from './utils/utils';
-export class ResponseError extends Error {
-    constructor(message, response) {
-        super(message);
-        Object.setPrototypeOf(this, ResponseError.prototype);
-        this.response = response;
-    }
-}
-/**
- * @param {string} url the URL to request; may include query string
- * @param {HttpDataFetcher<T> | NativeDataFetcherFunction<T>} fetcher the fetcher to use to perform the request
- * @param {ParsedUrlQueryInput} params the query string parameters to send with the request
- */
-export async function fetchData(url, fetcher, params = {}) {
-    const response = await fetcher(resolveUrl(url, params));
-    return response.data;
-}

package/form.d.ts

@@ -1 +0,0 @@
-export * from './types/form/index';

package/form.js

@@ -1 +0,0 @@
-module.exports = require('./dist/cjs/form/index');

package/types/data-fetcher.d.ts

@@ -1,34 +0,0 @@
-import { NativeDataFetcherFunction } from './native-fetcher';
-import { ParsedUrlQueryInput } from 'querystring';
-/**
- * Response data for an HTTP request sent to an API
- * @template T the type of data model requested
- */
-export interface HttpResponse<T> {
-    /** HTTP status code of the response (i.e. 200, 404) */
-    status: number;
-    /** HTTP status text of the response (i.e. 'OK', 'Bad Request') */
-    statusText: string;
-    /** Response content */
-    data: T;
-}
-/**
- * Describes functions that fetch data asynchronously (i.e. from an API endpoint).
- * This interface conforms to 'fetch' public API, but is adaptable to other HTTP libraries and
- * fetch polyfills.
- * The interface implementation must:
- * - Support SSR
- * - Comply with the rules of REST by returning appropriate response status codes when there is an error instead of throwing exceptions.
- * - Send HTTP POST requests if `data` param is specified; GET is suggested but not required for data-less requests
- */
-export type HttpDataFetcher<T> = (url: string, data?: unknown) => Promise<HttpResponse<T>>;
-export declare class ResponseError extends Error {
-    response: HttpResponse<unknown>;
-    constructor(message: string, response: HttpResponse<unknown>);
-}
-/**
- * @param {string} url the URL to request; may include query string
- * @param {HttpDataFetcher<T> | NativeDataFetcherFunction<T>} fetcher the fetcher to use to perform the request
- * @param {ParsedUrlQueryInput} params the query string parameters to send with the request
- */
-export declare function fetchData<T>(url: string, fetcher: HttpDataFetcher<T> | NativeDataFetcherFunction<T>, params?: ParsedUrlQueryInput): Promise<T>;