@stone-js/tencent-scf-adapter 0.8.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,74 @@
+# Stone.js - Tencent SCF Adapter
+
+[![npm](https://img.shields.io/npm/l/@stone-js/tencent-scf-adapter)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@stone-js/tencent-scf-adapter)](https://www.npmjs.com/package/@stone-js/tencent-scf-adapter)
+[![npm](https://img.shields.io/npm/dm/@stone-js/tencent-scf-adapter)](https://www.npmjs.com/package/@stone-js/tencent-scf-adapter)
+![Maintenance](https://img.shields.io/maintenance/yes/2026)
+[![Build Status](https://github.com/stone-foundation/stone-js-tencent-scf-adapter/actions/workflows/main.yml/badge.svg)](https://github.com/stone-foundation/stone-js-tencent-scf-adapter/actions/workflows/main.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-tencent-scf-adapter&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-tencent-scf-adapter)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
+
+The **Tencent SCF Adapter** lets your Stone.js application run on **event-driven** Tencent Cloud Serverless Cloud Function, beyond HTTP. It normalizes any non-HTTP trigger (COS, CMQ/TDMQ, Timer, CKafka) into a Stone.js `IncomingEvent`, fully aligned with the Continuum Architecture.
+
+> For **HTTP-triggered** functions, use [`@stone-js/tencent-scf-http-adapter`](https://www.npmjs.com/package/@stone-js/tencent-scf-http-adapter).
+
+---
+
+## Introduction
+
+In Stone.js, **adapters** are the translation layer between a platform and your domain. This adapter targets the non-HTTP SCF triggers: the function is invoked with `(event, context)`, and the adapter turns that into a standardized `IncomingEvent`, runs it through your kernel, and returns a raw response. The event payload is exposed on the event metadata, so one handler can dispatch on the trigger.
+
+It does **not** own a server: `run()` returns the `(event, context)` handler SCF invokes.
+
+## Installation
+
+```bash
+npm install @stone-js/tencent-scf-adapter
+# or
+pnpm add @stone-js/tencent-scf-adapter
+# or
+yarn add @stone-js/tencent-scf-adapter
+```
+
+> Requires `@stone-js/core` and `@stone-js/env` as peer dependencies.
+
+## Usage
+
+Declarative (decorator):
+
+```ts
+import { StoneApp } from '@stone-js/core'
+import { TencentScf } from '@stone-js/tencent-scf-adapter'
+
+@TencentScf()
+@StoneApp({ name: 'workers' })
+export class Application {}
+```
+
+Imperative (blueprint):
+
+```ts
+import { defineStoneApp } from '@stone-js/core'
+import { tencentScfAdapterBlueprint } from '@stone-js/tencent-scf-adapter'
+
+export const App = defineStoneApp({ name: 'workers' }, [tencentScfAdapterBlueprint])
+```
+
+`run()` returns the `(event, context)` handler SCF invokes:
+
+```ts
+// index.js — the SCF function entry
+exports.main_handler = await stoneApp.run()
+```
+
+### Failures and retries
+
+SCF treats an event invocation as **failed** only when the handler rejects. On failure the adapter rethrows by default so SCF's retry / dead-letter policy applies, set `stone.adapter.rethrowOnError = false` to opt out and manage failures yourself.
+
+## Documentation
+
+See the [official documentation](https://stonejs.dev/docs/adapters/tencent-scf) for the full guide.
+
+## License
+
+[MIT](./LICENSE)

package/dist/RawResponseWrapper.d.ts

@@ -0,0 +1,59 @@
+import { RawResponse } from './declarations';
+import { IRawResponseWrapper, RawResponseOptions } from '@stone-js/core';
+/**
+ * Wrapper for generic raw responses.
+ *
+ * The `RawResponseWrapper` is responsible for encapsulating a raw response
+ * and returning it in a structure that aligns with the Stone.js framework's requirements.
+ * It implements the `IRawResponseWrapper` interface, ensuring compatibility with the framework.
+ */
+export declare class RawResponseWrapper implements IRawResponseWrapper<RawResponse> {
+    private readonly options;
+    /**
+     * Factory method to create an instance of `RawResponseWrapper`.
+     *
+     * This method initializes the wrapper with a set of partial response options.
+     *
+     * @param options - Partial options to configure the raw response.
+     * @returns A new instance of `RawResponseWrapper`.
+     *
+     * @example
+     * ```typescript
+     * const responseWrapper = RawResponseWrapper.create({
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: { message: 'Success' },
+     *   statusCode: 200,
+     * });
+     *
+     * const response = responseWrapper.respond();
+     * console.log(response); // { headers: { 'Content-Type': 'application/json' }, body: { message: 'Success' }, statusCode: 200 }
+     * ```
+     */
+    static create(options: Partial<RawResponseOptions>): RawResponseWrapper;
+    /**
+     * Constructs an instance of `RawResponseWrapper`.
+     *
+     * This constructor is private and should not be called directly.
+     * Use the `create` method to initialize an instance.
+     *
+     * @param options - Partial options for configuring the raw response.
+     */
+    private constructor();
+    /**
+     * Constructs and returns the raw response.
+     *
+     * The `respond` method generates and returns the raw response based on
+     * the provided options. The response is returned as-is, allowing for
+     * maximum flexibility in defining its structure.
+     *
+     * @returns A `RawResponse` object containing the response options.
+     *
+     * @example
+     * ```typescript
+     * const responseWrapper = RawResponseWrapper.create({ body: 'Hello, world!' });
+     * const response = responseWrapper.respond();
+     * console.log(response); // { body: 'Hello, world!' }
+     * ```
+     */
+    respond(): RawResponse;
+}

package/dist/TencentScfAdapter.d.ts

@@ -0,0 +1,83 @@
+import { RawResponse, TencentScfEvent, TencentScfContext, TencentScfAdapterContext, TencentScfEventHandlerFunction } from './declarations';
+import { Adapter, IBlueprint, IncomingEvent, OutgoingResponse, IncomingEventOptions } from '@stone-js/core';
+/**
+ * Tencent SCF Adapter for Stone.js.
+ *
+ * The `TencentScfAdapter` provides seamless integration between Stone.js applications
+ * and the Tencent SCF environment. It processes incoming events from Tencent SCF,
+ * transforms them into `IncomingEvent` instances, and returns a `RawResponse`.
+ *
+ * This adapter ensures compatibility with Tencent SCF's execution model and
+ * abstracts the event handling process for Stone.js developers.
+ *
+ * @template TencentScfEvent - The type of the raw event received from Tencent SCF.
+ * @template RawResponse - The type of the response to send back to Tencent SCF.
+ * @template TencentScfContext - The Tencent SCF execution context type.
+ * @template IncomingEvent - The type of the processed incoming event.
+ * @template IncomingEventOptions - Options used to create an incoming event.
+ * @template OutgoingResponse - The type of the outgoing response after processing.
+ * @template TencentScfAdapterContext - Context type specific to the adapter.
+ *
+ * @extends Adapter
+ *
+ * @example
+ * ```typescript
+ * import { TencentScfAdapter } from '@stone-js/aws-lambda-adapter';
+ *
+ * const adapter = TencentScfAdapter.create({...});
+ *
+ * const handler = await adapter.run();
+ *
+ * export { handler };
+ * ```
+ *
+ * @see {@link https://stone-js.com/docs Stone.js Documentation}
+ * @see {@link https://docs.aws.amazon.com/lambda/ Tencent SCF Documentation}
+ */
+export declare class TencentScfAdapter extends Adapter<TencentScfEvent, RawResponse, TencentScfContext, IncomingEvent, IncomingEventOptions, OutgoingResponse, TencentScfAdapterContext> {
+    /**
+     * Creates an instance of the `TencentScfAdapter`.
+     *
+     * @param blueprint - The application blueprint.
+     * @returns A new instance of `TencentScfAdapter`.
+     *
+     * @example
+     * ```typescript
+     * const adapter = TencentScfAdapter.create(blueprint);
+     * await adapter.run();
+     * ```
+     */
+    static create(blueprint: IBlueprint): TencentScfAdapter;
+    /**
+     * Executes the adapter and provides an Tencent SCF-compatible handler function.
+     *
+     * The `run` method initializes the adapter and returns a handler function
+     * that Tencent SCF can invoke. This handler processes events, manages context,
+     * and returns the appropriate response.
+     *
+     * @template ExecutionResultType - The type representing the Tencent SCF event handler function.
+     * @returns A promise resolving to the Tencent SCF handler function.
+     * @throws {TencentScfAdapterError} If used outside the Tencent SCF environment.
+     */
+    run<ExecutionResultType = TencentScfEventHandlerFunction>(): Promise<ExecutionResultType>;
+    /**
+     * Initializes the adapter and validates its execution context.
+     *
+     * Ensures the adapter is running in an Tencent SCF environment. If not, it
+     * throws an error to prevent misuse.
+     *
+     * @throws {TencentScfAdapterError} If executed outside an Tencent SCF context (e.g., browser).
+     */
+    protected onStart(): Promise<void>;
+    /**
+     * Processes an incoming Tencent SCF event.
+     *
+     * This method transforms the raw Tencent SCF event into a Stone.js `IncomingEvent`,
+     * processes it through the pipeline, and generates a `RawResponse` to send back.
+     *
+     * @param rawEvent - The raw Tencent SCF event to be processed.
+     * @param executionContext - The Tencent SCF execution context for the event.
+     * @returns A promise resolving to the processed `RawResponse`.
+     */
+    protected eventListener(rawEvent: TencentScfEvent, executionContext: TencentScfContext): Promise<RawResponse>;
+}

package/dist/TencentScfErrorHandler.d.ts

@@ -0,0 +1,28 @@
+import { IBlueprint, AdapterErrorContext, IAdapterErrorHandler, AdapterEventBuilderType } from '@stone-js/core';
+import { TencentScfContext, TencentScfEvent, RawResponse } from './declarations';
+/**
+ * TencentScfErrorHandler options.
+ */
+export interface TencentScfErrorHandlerOptions {
+    blueprint: IBlueprint;
+}
+/**
+ * Class representing an TencentScfErrorHandler.
+ */
+export declare class TencentScfErrorHandler implements IAdapterErrorHandler<TencentScfEvent, RawResponse, TencentScfContext> {
+    private readonly logger;
+    /**
+     * Create an TencentScfErrorHandler.
+     *
+     * @param options - TencentScfErrorHandler options.
+     */
+    constructor({ blueprint }: TencentScfErrorHandlerOptions);
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @param context - The context of the adapter.
+     * @returns The raw response builder.
+     */
+    handle(error: Error, context: AdapterErrorContext<TencentScfEvent, RawResponse, TencentScfContext>): AdapterEventBuilderType<RawResponse>;
+}

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A constant representing the Tencent SCF platform identifier.
+ *
+ * This constant is used as an alias for the Tencent SCF Adapter within the Stone.js framework.
+ * It helps in identifying and configuring platform-specific adapters or components for handling
+ * incoming requests and responses.
+ */
+export declare const TENCENT_SCF_PLATFORM = "tencent_scf";

package/dist/declarations.d.ts

@@ -0,0 +1,42 @@
+import { RawResponseWrapper } from './RawResponseWrapper';
+import { AdapterContext, IAdapterEventBuilder, IncomingEvent, IncomingEventOptions, OutgoingResponse, RawResponseOptions } from '@stone-js/core';
+/**
+ * Represents a generic raw response as a key-value pair.
+ */
+export type RawResponse = Record<string, unknown>;
+/**
+ * The event payload delivered to a non-HTTP Tencent SCF function.
+ *
+ * The shape depends on the trigger, the COS object event, the CMQ/TDMQ message, the Timer payload,
+ * the CKafka records, etc. Kept generic; the handler inspects the event metadata.
+ */
+export type TencentScfEvent = Record<string, unknown>;
+/**
+ * The Tencent SCF invocation context (`context` argument).
+ *
+ * Carries `request_id`, `function_name`, `namespace`, the credentials and the logger.
+ */
+export type TencentScfContext = Record<string, unknown>;
+/**
+ * The Tencent SCF event handler: `(event, context) => Promise<...>`, the signature the SCF event
+ * (non-HTTP) trigger invokes.
+ *
+ * @template RawResponseType - The type of the response returned by the handler.
+ */
+export type TencentScfEventHandlerFunction<RawResponseType = RawResponse> = (rawEvent: TencentScfEvent, context: TencentScfContext) => Promise<RawResponseType>;
+/**
+ * Represents the response builder for the Tencent SCF Adapter.
+ */
+export type TencentScfAdapterResponseBuilder = IAdapterEventBuilder<RawResponseOptions, RawResponseWrapper>;
+/**
+ * Represents the context for the Tencent SCF Adapter.
+ *
+ * This interface extends `AdapterContext` and includes additional properties
+ * specific to generic Tencent SCF events.
+ */
+export interface TencentScfAdapterContext extends AdapterContext<TencentScfEvent, RawResponse, TencentScfContext, IncomingEvent, IncomingEventOptions, OutgoingResponse> {
+    /**
+     * The raw response associated with the current context.
+     */
+    rawResponse: RawResponse;
+}

package/dist/decorators/TencentScf.d.ts

@@ -0,0 +1,33 @@
+import { ClassType } from '@stone-js/core';
+import { TencentScfAdapterAdapterConfig } from '../options/TencentScfAdapterBlueprint';
+/**
+ * Configuration options for the `TencentScf` decorator.
+ * These options extend the default Tencent SCF adapter configuration.
+ */
+export interface TencentScfOptions extends Partial<TencentScfAdapterAdapterConfig> {
+}
+/**
+ * A Stone.js decorator that integrates the Tencent SCF Adapter with a class.
+ *
+ * This decorator modifies the class to seamlessly enable Tencent SCF as the
+ * execution environment for a Stone.js application. By applying this decorator,
+ * the class is automatically configured with the necessary blueprint for Tencent SCF.
+ *
+ * @template T - The type of the class being decorated. Defaults to `ClassType`.
+ * @param options - Optional configuration to customize the Tencent SCF Adapter.
+ *
+ * @returns A class decorator that applies the Tencent SCF adapter configuration.
+ *
+ * @example
+ * ```typescript
+ * import { TencentScf } from '@stone-js/tencent-scf-adapter';
+ *
+ * @TencentScf({
+ *   alias: 'MyTencentScf',
+ * })
+ * class App {
+ *   // Your application logic here
+ * }
+ * ```
+ */
+export declare const TencentScf: <T extends ClassType = ClassType>(options?: TencentScfOptions) => ClassDecorator;

package/dist/errors/TencentScfAdapterError.d.ts

@@ -0,0 +1,7 @@
+import { ErrorOptions, IntegrationError } from '@stone-js/core';
+/**
+ * Custom error for Tencent SCF adapter operations.
+ */
+export declare class TencentScfAdapterError extends IntegrationError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './RawResponseWrapper';
+export * from './TencentScfAdapter';
+export * from './TencentScfErrorHandler';
+export * from './constants';
+export * from './declarations';
+export * from './decorators/TencentScf';
+export * from './errors/TencentScfAdapterError';
+export * from './middleware/BlueprintMiddleware';
+export * from './middleware/IncomingEventMiddleware';
+export * from './options/TencentScfAdapterBlueprint';
+export * from './resolvers';

package/dist/index.js

@@ -0,0 +1,399 @@
+import { IntegrationError, Adapter, AdapterEventBuilder, IncomingEvent, defaultLoggerResolver, OutgoingResponse, defaultKernelResolver, isNotEmpty, classDecoratorLegacyWrapper, addBlueprint } from '@stone-js/core';
+import { getString } from '@stone-js/env';
+import { cloneValue, deepMerge } from '@stone-js/config';
+
+/**
+ * Wrapper for generic raw responses.
+ *
+ * The `RawResponseWrapper` is responsible for encapsulating a raw response
+ * and returning it in a structure that aligns with the Stone.js framework's requirements.
+ * It implements the `IRawResponseWrapper` interface, ensuring compatibility with the framework.
+ */
+class RawResponseWrapper {
+    options;
+    /**
+     * Factory method to create an instance of `RawResponseWrapper`.
+     *
+     * This method initializes the wrapper with a set of partial response options.
+     *
+     * @param options - Partial options to configure the raw response.
+     * @returns A new instance of `RawResponseWrapper`.
+     *
+     * @example
+     * ```typescript
+     * const responseWrapper = RawResponseWrapper.create({
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: { message: 'Success' },
+     *   statusCode: 200,
+     * });
+     *
+     * const response = responseWrapper.respond();
+     * console.log(response); // { headers: { 'Content-Type': 'application/json' }, body: { message: 'Success' }, statusCode: 200 }
+     * ```
+     */
+    static create(options) {
+        return new this(options);
+    }
+    /**
+     * Constructs an instance of `RawResponseWrapper`.
+     *
+     * This constructor is private and should not be called directly.
+     * Use the `create` method to initialize an instance.
+     *
+     * @param options - Partial options for configuring the raw response.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Constructs and returns the raw response.
+     *
+     * The `respond` method generates and returns the raw response based on
+     * the provided options. The response is returned as-is, allowing for
+     * maximum flexibility in defining its structure.
+     *
+     * @returns A `RawResponse` object containing the response options.
+     *
+     * @example
+     * ```typescript
+     * const responseWrapper = RawResponseWrapper.create({ body: 'Hello, world!' });
+     * const response = responseWrapper.respond();
+     * console.log(response); // { body: 'Hello, world!' }
+     * ```
+     */
+    respond() {
+        return this.options;
+    }
+}
+
+/**
+ * Custom error for Tencent SCF adapter operations.
+ */
+class TencentScfAdapterError extends IntegrationError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'TencentScfAdapterError';
+    }
+}
+
+/**
+ * Tencent SCF Adapter for Stone.js.
+ *
+ * The `TencentScfAdapter` provides seamless integration between Stone.js applications
+ * and the Tencent SCF environment. It processes incoming events from Tencent SCF,
+ * transforms them into `IncomingEvent` instances, and returns a `RawResponse`.
+ *
+ * This adapter ensures compatibility with Tencent SCF's execution model and
+ * abstracts the event handling process for Stone.js developers.
+ *
+ * @template TencentScfEvent - The type of the raw event received from Tencent SCF.
+ * @template RawResponse - The type of the response to send back to Tencent SCF.
+ * @template TencentScfContext - The Tencent SCF execution context type.
+ * @template IncomingEvent - The type of the processed incoming event.
+ * @template IncomingEventOptions - Options used to create an incoming event.
+ * @template OutgoingResponse - The type of the outgoing response after processing.
+ * @template TencentScfAdapterContext - Context type specific to the adapter.
+ *
+ * @extends Adapter
+ *
+ * @example
+ * ```typescript
+ * import { TencentScfAdapter } from '@stone-js/aws-lambda-adapter';
+ *
+ * const adapter = TencentScfAdapter.create({...});
+ *
+ * const handler = await adapter.run();
+ *
+ * export { handler };
+ * ```
+ *
+ * @see {@link https://stone-js.com/docs Stone.js Documentation}
+ * @see {@link https://docs.aws.amazon.com/lambda/ Tencent SCF Documentation}
+ */
+class TencentScfAdapter extends Adapter {
+    /**
+     * Creates an instance of the `TencentScfAdapter`.
+     *
+     * @param blueprint - The application blueprint.
+     * @returns A new instance of `TencentScfAdapter`.
+     *
+     * @example
+     * ```typescript
+     * const adapter = TencentScfAdapter.create(blueprint);
+     * await adapter.run();
+     * ```
+     */
+    static create(blueprint) {
+        return new this(blueprint);
+    }
+    /**
+     * Executes the adapter and provides an Tencent SCF-compatible handler function.
+     *
+     * The `run` method initializes the adapter and returns a handler function
+     * that Tencent SCF can invoke. This handler processes events, manages context,
+     * and returns the appropriate response.
+     *
+     * @template ExecutionResultType - The type representing the Tencent SCF event handler function.
+     * @returns A promise resolving to the Tencent SCF handler function.
+     * @throws {TencentScfAdapterError} If used outside the Tencent SCF environment.
+     */
+    async run() {
+        await this.onStart();
+        const handler = async (rawEvent, executionContext) => {
+            return await this.eventListener(rawEvent, executionContext);
+        };
+        return handler;
+    }
+    /**
+     * Initializes the adapter and validates its execution context.
+     *
+     * Ensures the adapter is running in an Tencent SCF environment. If not, it
+     * throws an error to prevent misuse.
+     *
+     * @throws {TencentScfAdapterError} If executed outside an Tencent SCF context (e.g., browser).
+     */
+    async onStart() {
+        if (typeof window === 'object') {
+            throw new TencentScfAdapterError('This `TencentScfAdapter` must be used only in Tencent SCF context.');
+        }
+        await this.executeHooks('onStart');
+    }
+    /**
+     * Processes an incoming Tencent SCF event.
+     *
+     * This method transforms the raw Tencent SCF event into a Stone.js `IncomingEvent`,
+     * processes it through the pipeline, and generates a `RawResponse` to send back.
+     *
+     * @param rawEvent - The raw Tencent SCF event to be processed.
+     * @param executionContext - The Tencent SCF execution context for the event.
+     * @returns A promise resolving to the processed `RawResponse`.
+     */
+    async eventListener(rawEvent, executionContext) {
+        const incomingEventBuilder = AdapterEventBuilder.create({
+            resolver: (options) => IncomingEvent.create(options)
+        });
+        const rawResponseBuilder = AdapterEventBuilder.create({
+            resolver: (options) => RawResponseWrapper.create(options)
+        });
+        const rawResponse = {};
+        const context = {
+            rawEvent,
+            rawResponse,
+            executionContext,
+            rawResponseBuilder,
+            incomingEventBuilder
+        };
+        let eventHandler;
+        try {
+            eventHandler = this.resolveEventHandler();
+            await this.executeEventHandlerHooks('onInit', eventHandler);
+            return await this.sendEventThroughDestination(context, eventHandler);
+        }
+        catch (error) {
+            const rawResponseBuilder = await this.handleError(error, context);
+            // Pass `eventHandler` so the kernel's `onTerminate` (log flush, connection close) runs on the
+            // error path too — the core only fires it when the handler is provided.
+            const response = await this.buildRawResponse({ ...context, rawResponseBuilder }, eventHandler);
+            // Tencent SCF only treats an event invocation (COS, CMQ/TDMQ, Timer, CKafka) as failed when
+            // the handler REJECTS. Swallowing the error and returning a value acknowledges the event and
+            // defeats SCF's retry / dead-letter policy — silent data loss. So by default we rethrow. An
+            // app that manages failures itself can opt out with `stone.adapter.rethrowOnError = false`.
+            if (this.blueprint.get('stone.adapter.rethrowOnError', true)) {
+                throw error;
+            }
+            return response;
+        }
+    }
+}
+
+/**
+ * A constant representing the Tencent SCF platform identifier.
+ *
+ * This constant is used as an alias for the Tencent SCF Adapter within the Stone.js framework.
+ * It helps in identifying and configuring platform-specific adapters or components for handling
+ * incoming requests and responses.
+ */
+const TENCENT_SCF_PLATFORM = 'tencent_scf';
+
+/**
+ * Class representing an TencentScfErrorHandler.
+ */
+class TencentScfErrorHandler {
+    logger;
+    /**
+     * Create an TencentScfErrorHandler.
+     *
+     * @param options - TencentScfErrorHandler options.
+     */
+    constructor({ blueprint }) {
+        this.logger = blueprint.get('stone.logger.resolver', defaultLoggerResolver)(blueprint);
+    }
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @param context - The context of the adapter.
+     * @returns The raw response builder.
+     */
+    handle(error, context) {
+        this.logger.error(error.message, { error });
+        return context
+            .rawResponseBuilder
+            .add('statusCode', 500);
+    }
+}
+
+/**
+ * Adapter resolver for generic Tencent SCF adapter.
+ *
+ * Creates and configures an `TencentScfAdapter` for handling generic events in Tencent SCF.
+ *
+ * @param blueprint - The `IBlueprint` providing configuration and dependencies.
+ * @returns An `TencentScfAdapter` instance.
+ */
+const tencentScfAdapterResolver = (blueprint) => {
+    return TencentScfAdapter.create(blueprint);
+};
+
+/**
+ * Middleware to dynamically set response resolver for adapter.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetTencentScfResponseResolverMiddleware(context, next)
+ * ```
+ */
+const SetTencentScfResponseResolverMiddleware = async (context, next) => {
+    if (context.blueprint.get('stone.adapter.platform') === TENCENT_SCF_PLATFORM) {
+        context.blueprint.set('stone.kernel.responseResolver', (options) => OutgoingResponse.create(options));
+    }
+    return await next(context);
+};
+/**
+ * Configuration for adapter processing middleware.
+ *
+ * This array defines a list of middleware pipes, each with a `pipe` function and a `priority`.
+ * These pipes are executed in the order of their priority values, with lower values running first.
+ */
+const metaAdapterBlueprintMiddleware = [
+    { module: SetTencentScfResponseResolverMiddleware, priority: 6 }
+];
+
+/**
+ * Middleware for handling incoming events and transforming them into Stone.js events.
+ *
+ * This class processes incoming events, extracting relevant data and forwards them to the next middleware in the pipeline.
+ */
+class IncomingEventMiddleware {
+    /**
+     * Handles the incoming event, processes it, and invokes the next middleware in the pipeline.
+     *
+     * @param context - The adapter context containing the raw event, execution context, and other data.
+     * @param next - The next middleware to be invoked in the pipeline.
+     * @returns A promise that resolves to the processed Response Builder.
+     * @throws {TencentScfAdapterError} If required components are missing in the context.
+     */
+    async handle(context, next) {
+        if ((context.rawEvent === undefined) || ((context.incomingEventBuilder?.add) === undefined)) {
+            throw new TencentScfAdapterError('The context is missing required components.');
+        }
+        context
+            .incomingEventBuilder
+            .add('metadata', context.rawEvent)
+            .add('source', this.getSource(context));
+        return await next(context);
+    }
+    /**
+     * Create the IncomingEventSource from the context.
+     *
+     * @param context - The adapter context containing the raw event, execution context, and other data.
+     * @returns The Incoming Event Source.
+     */
+    getSource(context) {
+        return {
+            rawEvent: context.rawEvent,
+            platform: TENCENT_SCF_PLATFORM,
+            rawContext: context.executionContext
+        };
+    }
+}
+/**
+ * Meta Middleware for processing incoming events.
+ */
+const MetaIncomingEventMiddleware = { module: IncomingEventMiddleware, isClass: true };
+
+/**
+ * Default blueprint configuration for the Tencent SCF Adapter.
+ *
+ * This blueprint defines the initial configuration for the Tencent SCF adapter
+ * within the Stone.js framework. It includes:
+ * - An alias for the Tencent SCF platform (`TENCENT_SCF_PLATFORM`).
+ * - A default resolver function (currently a placeholder).
+ * - Middleware, hooks, and state flags (`current`, `default`, `preferred`).
+ */
+const tencentScfAdapterBlueprint = {
+    stone: {
+        blueprint: {
+            middleware: metaAdapterBlueprintMiddleware
+        },
+        adapters: [
+            {
+                current: false,
+                variant: 'server',
+                platform: TENCENT_SCF_PLATFORM,
+                middleware: [
+                    MetaIncomingEventMiddleware
+                ],
+                resolver: tencentScfAdapterResolver,
+                eventHandlerResolver: defaultKernelResolver,
+                errorHandlers: {
+                    default: { module: TencentScfErrorHandler, isClass: true }
+                },
+                // The Tencent SCF runtime sets SCF_FUNCTIONNAME in the function environment.
+                default: isNotEmpty(getString('SCF_FUNCTIONNAME', ''))
+            }
+        ]
+    }
+};
+
+/**
+ * A Stone.js decorator that integrates the Tencent SCF Adapter with a class.
+ *
+ * This decorator modifies the class to seamlessly enable Tencent SCF as the
+ * execution environment for a Stone.js application. By applying this decorator,
+ * the class is automatically configured with the necessary blueprint for Tencent SCF.
+ *
+ * @template T - The type of the class being decorated. Defaults to `ClassType`.
+ * @param options - Optional configuration to customize the Tencent SCF Adapter.
+ *
+ * @returns A class decorator that applies the Tencent SCF adapter configuration.
+ *
+ * @example
+ * ```typescript
+ * import { TencentScf } from '@stone-js/tencent-scf-adapter';
+ *
+ * @TencentScf({
+ *   alias: 'MyTencentScf',
+ * })
+ * class App {
+ *   // Your application logic here
+ * }
+ * ```
+ */
+const TencentScf = (options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        // Clone the module-level default before merging so decorating a class never mutates the shared
+        // singleton (which would leak options across classes and tests).
+        const blueprint = cloneValue(tencentScfAdapterBlueprint);
+        if (blueprint.stone?.adapters?.[0] !== undefined) {
+            blueprint.stone.adapters[0] = deepMerge(blueprint.stone.adapters[0], options);
+        }
+        addBlueprint(target, context, blueprint);
+    });
+};
+
+export { IncomingEventMiddleware, MetaIncomingEventMiddleware, RawResponseWrapper, SetTencentScfResponseResolverMiddleware, TENCENT_SCF_PLATFORM, TencentScf, TencentScfAdapter, TencentScfAdapterError, TencentScfErrorHandler, metaAdapterBlueprintMiddleware, tencentScfAdapterBlueprint, tencentScfAdapterResolver };

package/dist/middleware/BlueprintMiddleware.d.ts

@@ -0,0 +1,21 @@
+import { ClassType, BlueprintContext, IBlueprint, MetaMiddleware, NextMiddleware } from '@stone-js/core';
+/**
+ * Middleware to dynamically set response resolver for adapter.
+ *
+ * @param context - The configuration context containing modules and blueprint.
+ * @param next - The next pipeline function to continue processing.
+ * @returns The updated blueprint or a promise resolving to it.
+ *
+ * @example
+ * ```typescript
+ * SetTencentScfResponseResolverMiddleware(context, next)
+ * ```
+ */
+export declare const SetTencentScfResponseResolverMiddleware: (context: BlueprintContext<IBlueprint, ClassType>, next: NextMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>) => Promise<IBlueprint>;
+/**
+ * Configuration for adapter processing middleware.
+ *
+ * This array defines a list of middleware pipes, each with a `pipe` function and a `priority`.
+ * These pipes are executed in the order of their priority values, with lower values running first.
+ */
+export declare const metaAdapterBlueprintMiddleware: Array<MetaMiddleware<BlueprintContext<IBlueprint, ClassType>, IBlueprint>>;

package/dist/middleware/IncomingEventMiddleware.d.ts

@@ -0,0 +1,29 @@
+import { NextMiddleware, type MetaMiddleware } from '@stone-js/core';
+import { TencentScfAdapterContext, TencentScfAdapterResponseBuilder } from '../declarations';
+/**
+ * Middleware for handling incoming events and transforming them into Stone.js events.
+ *
+ * This class processes incoming events, extracting relevant data and forwards them to the next middleware in the pipeline.
+ */
+export declare class IncomingEventMiddleware {
+    /**
+     * Handles the incoming event, processes it, and invokes the next middleware in the pipeline.
+     *
+     * @param context - The adapter context containing the raw event, execution context, and other data.
+     * @param next - The next middleware to be invoked in the pipeline.
+     * @returns A promise that resolves to the processed Response Builder.
+     * @throws {TencentScfAdapterError} If required components are missing in the context.
+     */
+    handle(context: TencentScfAdapterContext, next: NextMiddleware<TencentScfAdapterContext, TencentScfAdapterResponseBuilder>): Promise<TencentScfAdapterResponseBuilder>;
+    /**
+     * Create the IncomingEventSource from the context.
+     *
+     * @param context - The adapter context containing the raw event, execution context, and other data.
+     * @returns The Incoming Event Source.
+     */
+    private getSource;
+}
+/**
+ * Meta Middleware for processing incoming events.
+ */
+export declare const MetaIncomingEventMiddleware: MetaMiddleware<any, any>;

package/dist/options/TencentScfAdapterBlueprint.d.ts

@@ -0,0 +1,30 @@
+import { TencentScfContext, TencentScfEvent, RawResponse } from '../declarations';
+import { AdapterConfig, IncomingEvent, IncomingEventOptions, OutgoingResponse, StoneBlueprint } from '@stone-js/core';
+/**
+ * Configuration interface for the Tencent SCF Adapter.
+ *
+ * Extends the `AdapterConfig` interface from the Stone.js framework and provides
+ * customizable options specific to the Tencent SCF platform. This includes
+ * alias, resolver, middleware, hooks, and various adapter state flags.
+ */
+export interface TencentScfAdapterAdapterConfig extends AdapterConfig<TencentScfEvent, RawResponse, TencentScfContext, IncomingEvent, IncomingEventOptions, OutgoingResponse> {
+}
+/**
+ * Blueprint interface for the Tencent SCF Adapter.
+ *
+ * This interface extends `StoneBlueprint` and defines the structure of the
+ * Tencent SCF adapter blueprint used in the Stone.js framework. It includes
+ * a `stone` object with an array of `TencentScfAdapterConfig` items.
+ */
+export interface TencentScfAdapterBlueprint extends StoneBlueprint {
+}
+/**
+ * Default blueprint configuration for the Tencent SCF Adapter.
+ *
+ * This blueprint defines the initial configuration for the Tencent SCF adapter
+ * within the Stone.js framework. It includes:
+ * - An alias for the Tencent SCF platform (`TENCENT_SCF_PLATFORM`).
+ * - A default resolver function (currently a placeholder).
+ * - Middleware, hooks, and state flags (`current`, `default`, `preferred`).
+ */
+export declare const tencentScfAdapterBlueprint: TencentScfAdapterBlueprint;

package/dist/resolvers.d.ts

@@ -0,0 +1,10 @@
+import { AdapterResolver } from '@stone-js/core';
+/**
+ * Adapter resolver for generic Tencent SCF adapter.
+ *
+ * Creates and configures an `TencentScfAdapter` for handling generic events in Tencent SCF.
+ *
+ * @param blueprint - The `IBlueprint` providing configuration and dependencies.
+ * @returns An `TencentScfAdapter` instance.
+ */
+export declare const tencentScfAdapterResolver: AdapterResolver;

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@stone-js/tencent-scf-adapter",
+  "version": "0.8.0",
+  "description": "General-purpose Tencent Cloud SCF adapter for Stone.js, run any app on event-driven Serverless Cloud Function triggers, beyond HTTP. Supports COS, CMQ/TDMQ, Timer and CKafka.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-tencent-scf-adapter"
+  },
+  "homepage": "https://stonejs.dev",
+  "bugs": {
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
+  },
+  "keywords": [
+    "tencent",
+    "tencent-cloud",
+    "scf",
+    "serverless-cloud-function",
+    "faas",
+    "serverless",
+    "cos",
+    "timer",
+    "china",
+    "adapter",
+    "Stone.js"
+  ],
+  "files": [
+    "/dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "peerDependencies": {
+    "@stone-js/core": "0.8.0",
+    "@stone-js/env": "0.8.0"
+  },
+  "dependencies": {
+    "@stone-js/config": "0.8.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-multi-entry": "^6.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.44.1",
+    "rollup-plugin-node-externals": "^8.0.1",
+    "ts-standard": "^12.0.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "ts-standard": {
+    "globals": [
+      "it",
+      "test",
+      "expect",
+      "describe",
+      "beforeEach"
+    ]
+  },
+  "scripts": {
+    "lint": "ts-standard src",
+    "lint:fix": "ts-standard --fix src tests",
+    "predoc": "rimraf docs",
+    "doc": "typedoc",
+    "clean": "rimraf dist",
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage",
+    "test:text": "npm run test:cvg -- --coverage.reporter=text",
+    "test:html": "npm run test:cvg -- --coverage.reporter=html",
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+  }
+}