@lokalise/connector-shell 1.1.0

package/README.md

@@ -0,0 +1,140 @@
+# @lokalise/connector-shell
+
+A drop-in module for [opinionated-machine](https://github.com/lokalise/opinionated-machine) services that provides the connector shell infrastructure for Lokalise Content Engine connectors.
+
+This package provides the generic connector shell with all standard controllers (Auth, Cache, Env, ItemList, ItemGroup, Publish, Translate) and routing logic. It's designed to work with any set of adapters through automatic adapter discovery via dependency injection tags.
+
+## Features
+
+- **Drop-in Integration**: Add to your modules list alongside adapter modules
+- **Automatic Adapter Discovery**: Finds adapters via DI tags (`ADAPTER_LABEL = 'connectorAdapter'`)
+- **Complete Controller Suite**: All 7 standard controllers included
+- **Type-Safe**: Full TypeScript support
+
+## Installation
+
+```bash
+npm install @lokalise/connector-shell
+```
+
+## Quick Start
+
+```typescript
+// modules.ts
+export const ALL_MODULES = [
+  new CommonModule(),          // Provides required dependencies
+  new YourAdapterModule(),     // Registers adapters with ADAPTER_LABEL tag
+  new ConnectorShellModule(),  // Discovers adapters, registers controllers
+]
+```
+
+## Required Dependencies
+
+Your `CommonModule` must provide:
+
+```typescript
+import { ADAPTER_LABEL } from '@lokalise/connector-adapter-common'
+import type { ProtectedRouteMetadataMapperFactory } from '@lokalise/connector-shell'
+
+export class CommonModule extends AbstractModule<CommonDependencies> {
+  resolveDependencies() {
+    return {
+      awilixManager: asSingletonFunction((deps) => deps.app?.awilixManager),
+      protectedRouteMetadataMapperFactory: asSingletonFunction(
+        (): ProtectedRouteMetadataMapperFactory => PROTECTED_ROUTE_METADATA_MAPPER
+      ),
+    }
+  }
+}
+
+export interface CommonDependencies {
+  awilixManager: AwilixManager
+  protectedRouteMetadataMapperFactory: ProtectedRouteMetadataMapperFactory
+}
+```
+
+**Example prehandler:**
+
+```typescript
+// prehandlers/integrationConfigPrehandler.ts
+export const PROTECTED_ROUTE_METADATA_MAPPER = (requireAuthConfig = true) =>
+  (() => ({
+    preHandler: (req, res, done) => {
+      // Decode ce-config and ce-auth headers, attach to req
+      done()
+    }
+  })) satisfies ApiContractMetadataToRouteMapper
+```
+
+## Adapter Discovery
+
+Adapters are discovered via the `ADAPTER_LABEL` tag:
+
+```typescript
+import { ADAPTER_LABEL, type Adapter } from '@lokalise/connector-adapter-common'
+import { AbstractModule, asSingletonClass } from 'opinionated-machine'
+
+export class YourAdapterModule extends AbstractModule<YourDependencies> {
+  resolveDependencies() {
+    return {
+      yourApiClient: asSingletonClass(YourApiClient),
+      yourAdapter: asSingletonClass(YourAdapter, {
+        tags: [ADAPTER_LABEL], // <-- Required for discovery
+      }),
+    }
+  }
+}
+```
+
+**How it works:**
+- `ADAPTER_LABEL = 'connectorAdapter'` (constant from `@lokalise/connector-adapter-common`)
+- ConnectorShellModule queries `awilixManager.getWithTags([ADAPTER_LABEL])` to find all adapters
+- Adapters are keyed by `adapter.getConnectorName()` value
+- Controllers resolve adapters per-request via `ce-connector-id` header
+
+## Creating Your ConnectorShellModule
+
+```typescript
+import {
+  ConnectorShellModule as BaseConnectorShellModule,
+  type ConnectorShellBaseDependencies,
+} from '@lokalise/connector-shell'
+
+export type SupportedConnectors =
+  | typeof YourAdapter.connectorName
+  | 'another-connector'
+
+export type ConnectorShellInjectableDependencies =
+  ConnectorShellBaseDependencies &
+  CommonDependencies &
+  YourAdapterPublicDependencies
+
+export class ConnectorShellModule extends BaseConnectorShellModule<
+  ConnectorShellInjectableDependencies,
+  ExternalDependencies
+> {}
+```
+
+## Bootstrap
+
+```typescript
+import { DIContext } from 'opinionated-machine'
+import { ALL_MODULES } from './modules'
+
+const diContext = new DIContext(diContainer, options)
+diContext.registerDependencies({ modules: ALL_MODULES }, externalDependencies)
+
+app.after(() => {
+  diContext.registerRoutes(app) // Controllers auto-register
+})
+```
+
+## Adding a New Adapter
+
+1. Create adapter implementing `Adapter` interface
+2. Register with `ADAPTER_LABEL` tag:
+   ```typescript
+   yourAdapter: asSingletonClass(YourAdapter, {
+     tags: [ADAPTER_LABEL],
+   })
+   ```

package/dist/ConnectorShellModule.d.ts

@@ -0,0 +1,59 @@
+import { type Adapter } from '@lokalise/connector-adapter-common';
+import type { ApiContractMetadataToRouteMapper } from '@lokalise/fastify-api-contracts';
+import { AbstractModule, type DependencyInjectionOptions, type MandatoryNameAndRegistrationPair } from 'opinionated-machine';
+/**
+ * Factory function that creates a metadata mapper for protected routes.
+ * The metadata mapper is responsible for adding prehandlers to routes.
+ * Applications should provide their own implementation.
+ */
+export type ProtectedRouteMetadataMapperFactory = (requireAuthConfig?: boolean) => ApiContractMetadataToRouteMapper;
+/**
+ * Base dependencies required by ConnectorShellModule.
+ * Applications should extend this with their own CommonDependencies and adapter public dependencies.
+ */
+export interface ConnectorShellBaseDependencies {
+    awilixManager: {
+        getWithTags: (tags: string[]) => Record<string, unknown>;
+    };
+    /**
+     * Factory function for creating protected route metadata mappers.
+     * This must be provided by the application.
+     */
+    protectedRouteMetadataMapperFactory: ProtectedRouteMetadataMapperFactory;
+}
+/**
+ * Dependencies that ConnectorShellModule creates
+ */
+interface ConnectorShellCreatedDependencies {
+    adapters: Record<string, Adapter>;
+}
+/**
+ * Generic ConnectorShellModule that works with any set of adapters.
+ * No hardcoded adapter imports - adapters are discovered at runtime via ADAPTER_LABEL tag.
+ *
+ * @example
+ * ```typescript
+ * // In your application
+ * export type ConnectorShellInjectableDependencies =
+ *   ConnectorShellBaseDependencies &
+ *   YourCommonDependencies &
+ *   YourAdapterPublicDependencies
+ *
+ * export type SupportedConnectors =
+ *   | typeof YourAdapter1.connectorName
+ *   | typeof YourAdapter2.connectorName
+ * ```
+ */
+export declare class ConnectorShellModule<TDependencies extends ConnectorShellBaseDependencies = ConnectorShellBaseDependencies, TExternalDependencies = unknown> extends AbstractModule<ConnectorShellCreatedDependencies, TExternalDependencies> {
+    resolveDependencies(_diOptions: DependencyInjectionOptions, _externalDependencies: TExternalDependencies): {
+        adapters: import("awilix").BuildResolver<Record<string, Adapter>> & import("awilix").DisposableResolver<Record<string, Adapter>>;
+    };
+    resolveControllers(): MandatoryNameAndRegistrationPair<unknown>;
+}
+/**
+ * Dependencies provided by ConnectorShellModule (includes both created and required dependencies)
+ */
+export type ConnectorShellDependencies = ConnectorShellCreatedDependencies & {
+    protectedRouteMetadataMapperFactory: ProtectedRouteMetadataMapperFactory;
+};
+export {};

package/dist/ConnectorShellModule.js

@@ -0,0 +1,51 @@
+import { ADAPTER_LABEL } from '@lokalise/connector-adapter-common';
+import { AbstractModule, asControllerClass, asSingletonFunction, } from 'opinionated-machine';
+import { AuthController } from "./auth/authController.js";
+import { CacheController } from "./cache/cacheController.js";
+import { EnvController } from "./env/envController.js";
+import { ItemGroupController } from "./itemGroup/ItemGroupController.js";
+import { ItemListController } from "./itemList/ItemListController.js";
+import { PublishController } from "./publish/publishController.js";
+import { TranslateController } from "./translate/translateController.js";
+/**
+ * Generic ConnectorShellModule that works with any set of adapters.
+ * No hardcoded adapter imports - adapters are discovered at runtime via ADAPTER_LABEL tag.
+ *
+ * @example
+ * ```typescript
+ * // In your application
+ * export type ConnectorShellInjectableDependencies =
+ *   ConnectorShellBaseDependencies &
+ *   YourCommonDependencies &
+ *   YourAdapterPublicDependencies
+ *
+ * export type SupportedConnectors =
+ *   | typeof YourAdapter1.connectorName
+ *   | typeof YourAdapter2.connectorName
+ * ```
+ */
+export class ConnectorShellModule extends AbstractModule {
+    resolveDependencies(_diOptions, _externalDependencies) {
+        return {
+            adapters: asSingletonFunction((dependencies) => {
+                const adapterMap = dependencies.awilixManager.getWithTags([ADAPTER_LABEL]);
+                return Object.values(adapterMap).reduce((acc, adapter) => {
+                    acc[adapter.getConnectorName()] = adapter;
+                    return acc;
+                }, {});
+            }),
+        };
+    }
+    resolveControllers() {
+        return {
+            authController: asControllerClass(AuthController),
+            cacheController: asControllerClass(CacheController),
+            publishController: asControllerClass(PublishController),
+            itemListController: asControllerClass(ItemListController),
+            itemGroupController: asControllerClass(ItemGroupController),
+            translateController: asControllerClass(TranslateController),
+            envController: asControllerClass(EnvController),
+        };
+    }
+}
+//# sourceMappingURL=ConnectorShellModule.js.map

package/dist/ConnectorShellModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectorShellModule.js","sourceRoot":"","sources":["../src/ConnectorShellModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,MAAM,oCAAoC,CAAA;AAEhF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AAiCxE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,oBAGX,SAAQ,cAAwE;IAChF,mBAAmB,CACjB,UAAsC,EACtC,qBAA4C;QAE5C,OAAO;YACL,QAAQ,EAAE,mBAAmB,CAAC,CAAC,YAA2B,EAA2B,EAAE;gBACrF,MAAM,UAAU,GAAG,YAAY,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,aAAa,CAAC,CAGxE,CAAA;gBACD,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CACrC,CAAC,GAAG,EAAE,OAAgB,EAAE,EAAE;oBACxB,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,GAAG,OAAO,CAAA;oBACzC,OAAO,GAAG,CAAA;gBACZ,CAAC,EACD,EAAE,CACH,CAAA;YACH,CAAC,CAAC;SACH,CAAA;IACH,CAAC;IAED,kBAAkB;QAChB,OAAO;YACL,cAAc,EAAE,iBAAiB,CAAC,cAAc,CAAC;YACjD,eAAe,EAAE,iBAAiB,CAAC,eAAe,CAAC;YACnD,iBAAiB,EAAE,iBAAiB,CAAC,iBAAiB,CAAC;YACvD,kBAAkB,EAAE,iBAAiB,CAAC,kBAAkB,CAAC;YACzD,mBAAmB,EAAE,iBAAiB,CAAC,mBAAmB,CAAC;YAC3D,mBAAmB,EAAE,iBAAiB,CAAC,mBAAmB,CAAC;YAC3D,aAAa,EAAE,iBAAiB,CAAC,aAAa,CAAC;SAChD,CAAA;IACH,CAAC;CACF"}

package/dist/adapterResolver/errors/adapterErrors.d.ts

@@ -0,0 +1,10 @@
+import { PublicNonRecoverableError } from '@lokalise/node-core';
+export declare class ConnectorNotSupportedError extends PublicNonRecoverableError {
+    constructor(connectorId: string);
+}
+export declare class ConnectorNotProvidedError extends PublicNonRecoverableError {
+    constructor();
+}
+export declare class MultipleConnectorsProvidedError extends PublicNonRecoverableError {
+    constructor(connectorIds: string[]);
+}

package/dist/adapterResolver/errors/adapterErrors.js

@@ -0,0 +1,40 @@
+import { CONNECTOR_ID_HEADER } from '@lokalise/connector-api-contracts';
+import { PublicNonRecoverableError } from '@lokalise/node-core';
+export class ConnectorNotSupportedError extends PublicNonRecoverableError {
+    constructor(connectorId) {
+        super({
+            message: 'Connector not supported',
+            errorCode: 'CONNECTOR_NOT_SUPPORTED',
+            httpStatusCode: 400,
+            details: {
+                connectorId,
+            },
+        });
+    }
+}
+export class ConnectorNotProvidedError extends PublicNonRecoverableError {
+    constructor() {
+        super({
+            message: 'Connector not provided',
+            errorCode: 'CONNECTOR_NOT_PROVIDED',
+            httpStatusCode: 400,
+            details: {
+                hint: `Make sure you provide connector id under ${CONNECTOR_ID_HEADER} header`,
+            },
+        });
+    }
+}
+export class MultipleConnectorsProvidedError extends PublicNonRecoverableError {
+    constructor(connectorIds) {
+        super({
+            message: 'Multiple connectors provided',
+            errorCode: 'MULTIPLE_CONNECTORS_PROVIDED',
+            httpStatusCode: 400,
+            details: {
+                providedConnectorIds: connectorIds,
+                hint: `Make sure you provide only one ${CONNECTOR_ID_HEADER} header value`,
+            },
+        });
+    }
+}
+//# sourceMappingURL=adapterErrors.js.map

package/dist/adapterResolver/errors/adapterErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapterErrors.js","sourceRoot":"","sources":["../../../src/adapterResolver/errors/adapterErrors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAE/D,MAAM,OAAO,0BAA2B,SAAQ,yBAAyB;IACvE,YAAY,WAAmB;QAC7B,KAAK,CAAC;YACJ,OAAO,EAAE,yBAAyB;YAClC,SAAS,EAAE,yBAAyB;YACpC,cAAc,EAAE,GAAG;YACnB,OAAO,EAAE;gBACP,WAAW;aACZ;SACF,CAAC,CAAA;IACJ,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,yBAAyB;IACtE;QACE,KAAK,CAAC;YACJ,OAAO,EAAE,wBAAwB;YACjC,SAAS,EAAE,wBAAwB;YACnC,cAAc,EAAE,GAAG;YACnB,OAAO,EAAE;gBACP,IAAI,EAAE,4CAA4C,mBAAmB,SAAS;aAC/E;SACF,CAAC,CAAA;IACJ,CAAC;CACF;AAED,MAAM,OAAO,+BAAgC,SAAQ,yBAAyB;IAC5E,YAAY,YAAsB;QAChC,KAAK,CAAC;YACJ,OAAO,EAAE,8BAA8B;YACvC,SAAS,EAAE,8BAA8B;YACzC,cAAc,EAAE,GAAG;YACnB,OAAO,EAAE;gBACP,oBAAoB,EAAE,YAAY;gBAClC,IAAI,EAAE,kCAAkC,mBAAmB,eAAe;aAC3E;SACF,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/adapterResolver/resolveAdapter.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from '@lokalise/connector-adapter-common';
+export declare const resolveAdapter: (adapters: Record<string, Adapter>, connectorId: string | string[] | undefined) => Adapter;

package/dist/adapterResolver/resolveAdapter.js

@@ -0,0 +1,16 @@
+import { ConnectorNotProvidedError, ConnectorNotSupportedError, MultipleConnectorsProvidedError, } from "./errors/adapterErrors.js";
+export const resolveAdapter = (adapters, connectorId) => {
+    if (!connectorId) {
+        throw new ConnectorNotProvidedError();
+    }
+    if (Array.isArray(connectorId) && connectorId.length !== 1) {
+        throw new MultipleConnectorsProvidedError(connectorId);
+    }
+    const singleConnectorId = (Array.isArray(connectorId) ? connectorId[0] : connectorId);
+    const adapter = adapters[singleConnectorId];
+    if (!adapter) {
+        throw new ConnectorNotSupportedError(singleConnectorId);
+    }
+    return adapter;
+};
+//# sourceMappingURL=resolveAdapter.js.map

package/dist/adapterResolver/resolveAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAdapter.js","sourceRoot":"","sources":["../../src/adapterResolver/resolveAdapter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,+BAA+B,GAChC,MAAM,2BAA2B,CAAA;AAElC,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,QAAiC,EACjC,WAA0C,EACjC,EAAE;IACX,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,yBAAyB,EAAE,CAAA;IACvC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,+BAA+B,CAAC,WAAW,CAAC,CAAA;IACxD,CAAC;IAED,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAW,CAAA;IAE/F,MAAM,OAAO,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IAE3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,0BAA0B,CAAC,iBAAiB,CAAC,CAAA;IACzD,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA"}

package/dist/auth/authController.d.ts

@@ -0,0 +1,55 @@
+import { AbstractController, type BuildRoutesReturnType } from 'opinionated-machine';
+import type { ConnectorShellDependencies } from '../ConnectorShellModule.ts';
+import '../commonTypes.ts';
+type AuthControllerContractsType = typeof AuthController.contracts;
+export declare class AuthController extends AbstractController<AuthControllerContractsType> {
+    static contracts: {
+        readonly postAuth: import("@lokalise/api-contracts").PayloadRouteDefinition<import("zod/v4").ZodUnion<readonly [import("zod/v4").ZodObject<{
+            redirectUrl: import("zod/v4").ZodString;
+            state: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, import("zod/v4").ZodOptional<import("zod/v4").ZodNull>]>, import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>, undefined, undefined, import("zod/v4").ZodObject<{
+            'ce-config': import("zod/v4").ZodString;
+            "x-connector-id": import("zod/v4").ZodString;
+        }, import("zod/v4/core").$strip>, undefined, false, false, {
+            200: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+            403: import("zod/v4").ZodObject<{
+                message: import("zod/v4").ZodString;
+                statusCode: import("zod/v4").ZodNumber;
+            }, import("zod/v4/core").$strip>;
+        }>;
+        readonly postAuthRefresh: import("@lokalise/api-contracts").PayloadRouteDefinition<import("zod/v4").ZodOptional<import("zod/v4").ZodNull>, import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>, undefined, undefined, import("zod/v4").ZodObject<{
+            'ce-config': import("zod/v4").ZodString;
+            'ce-auth': import("zod/v4").ZodString;
+            "x-connector-id": import("zod/v4").ZodString;
+        }, import("zod/v4/core").$strip>, undefined, false, false, {
+            200: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+            403: import("zod/v4").ZodObject<{
+                message: import("zod/v4").ZodString;
+                statusCode: import("zod/v4").ZodNumber;
+            }, import("zod/v4/core").$strip>;
+        }>;
+        readonly postAuthResponse: import("@lokalise/api-contracts").PayloadRouteDefinition<import("zod/v4").ZodObject<{
+            query: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+            body: import("zod/v4").ZodOptional<import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>>;
+            redirectUrl: import("zod/v4").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>, undefined, undefined, import("zod/v4").ZodObject<{
+            'ce-config': import("zod/v4").ZodString;
+            "x-connector-id": import("zod/v4").ZodString;
+        }, import("zod/v4/core").$strip>, undefined, false, false, {
+            200: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+            403: import("zod/v4").ZodObject<{
+                message: import("zod/v4").ZodString;
+                errorCode: import("zod/v4").ZodNumber;
+                details: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+            }, import("zod/v4/core").$strip>;
+        }>;
+    };
+    private readonly adapters;
+    private readonly protectedRouteMetadataMapper;
+    constructor(dependencies: ConnectorShellDependencies);
+    private get postAuth();
+    private get postAuthRefresh();
+    private get postAuthResponse();
+    buildRoutes(): BuildRoutesReturnType<AuthControllerContractsType>;
+}
+export {};

package/dist/auth/authController.js

@@ -0,0 +1,73 @@
+import { OAuthNotSupportedError } from '@lokalise/connector-adapter-common';
+import { CONNECTOR_ID_HEADER, postAuthContract, postAuthRefreshContract, postAuthResponseContract, } from '@lokalise/connector-api-contracts';
+import { buildFastifyPayloadRoute } from '@lokalise/fastify-api-contracts';
+import { InternalError } from '@lokalise/node-core';
+import { AbstractController } from 'opinionated-machine';
+import { resolveAdapter } from "../adapterResolver/resolveAdapter.js";
+import "../commonTypes.js";
+export class AuthController extends AbstractController {
+    static contracts = {
+        postAuth: postAuthContract,
+        postAuthRefresh: postAuthRefreshContract,
+        postAuthResponse: postAuthResponseContract,
+    };
+    adapters;
+    protectedRouteMetadataMapper;
+    constructor(dependencies) {
+        super();
+        this.adapters = dependencies.adapters;
+        this.protectedRouteMetadataMapper = dependencies.protectedRouteMetadataMapperFactory;
+    }
+    get postAuth() {
+        return buildFastifyPayloadRoute(postAuthContract, async (req, reply) => {
+            const adapter = resolveAdapter(this.adapters, req.headers[CONNECTOR_ID_HEADER]);
+            if (adapter.authServiceAPIKey) {
+                const authConfig = await adapter.authServiceAPIKey.validate(req.integrationConfig, req.reqContext);
+                return reply.send(authConfig);
+            }
+            if (adapter.authServiceOAuth) {
+                const authorizationUrl = await adapter.authServiceOAuth.generateAuthorizationUrl(req.integrationConfig, req.body, req.reqContext);
+                return reply.send({
+                    url: authorizationUrl,
+                });
+            }
+            throw new InternalError({
+                message: 'No auth service defined for connector',
+                errorCode: 'NO_AUTH_SERVICE_DEFINED',
+                details: {
+                    connectorName: adapter.getConnectorName(),
+                },
+            });
+        }, this.protectedRouteMetadataMapper(false));
+    }
+    get postAuthRefresh() {
+        return buildFastifyPayloadRoute(postAuthRefreshContract, async (req, reply) => {
+            const adapter = resolveAdapter(this.adapters, req.headers[CONNECTOR_ID_HEADER]);
+            const resolvedAuthService = adapter.authServiceOAuth;
+            if (!resolvedAuthService) {
+                throw new OAuthNotSupportedError(adapter.getConnectorName());
+            }
+            const authConfig = await resolvedAuthService.refresh(req.integrationConfig, req.authConfig, req.reqContext);
+            return reply.send(authConfig);
+        }, this.protectedRouteMetadataMapper());
+    }
+    get postAuthResponse() {
+        return buildFastifyPayloadRoute(postAuthResponseContract, async (req, reply) => {
+            const adapter = resolveAdapter(this.adapters, req.headers[CONNECTOR_ID_HEADER]);
+            const resolvedAuthService = adapter.authServiceOAuth;
+            if (!resolvedAuthService) {
+                throw new OAuthNotSupportedError(adapter.getConnectorName());
+            }
+            const credentials = await resolvedAuthService.getAuthCredentials(req.body, req.reqContext);
+            return reply.send(credentials);
+        }, this.protectedRouteMetadataMapper(false));
+    }
+    buildRoutes() {
+        return {
+            postAuth: this.postAuth,
+            postAuthRefresh: this.postAuthRefresh,
+            postAuthResponse: this.postAuthResponse,
+        };
+    }
+}
+//# sourceMappingURL=authController.js.map

package/dist/auth/authController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authController.js","sourceRoot":"","sources":["../../src/auth/authController.ts"],"names":[],"mappings":"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"}

package/dist/cache/cacheController.d.ts

@@ -0,0 +1,85 @@
+import { AbstractController, type BuildRoutesReturnType } from 'opinionated-machine';
+import type { ConnectorShellDependencies } from '../ConnectorShellModule.ts';
+import '../commonTypes.ts';
+type CacheControllerContractsType = typeof CacheController.contracts;
+export declare class CacheController extends AbstractController<CacheControllerContractsType> {
+    static contracts: {
+        readonly getCache: import("@lokalise/api-contracts").GetRouteDefinition<import("zod/v4").ZodObject<{
+            items: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                uniqueId: import("zod/v4").ZodString;
+                groupId: import("zod/v4").ZodString;
+                metadata: import("zod/v4").ZodRecord<import("zod/v4").ZodAny, import("zod/v4").ZodAny>;
+            }, import("zod/v4/core").$strip>>;
+            next: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+            hasMore: import("zod/v4").ZodOptional<import("zod/v4").ZodBoolean>;
+            nextCursor: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, undefined, import("zod/v4").ZodObject<{
+            next: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+            maxItems: import("zod/v4").ZodOptional<import("zod/v4").ZodNumber>;
+            cursor: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, import("zod/v4").ZodObject<{
+            'ce-config': import("zod/v4").ZodString;
+            'ce-auth': import("zod/v4").ZodString;
+            "x-connector-id": import("zod/v4").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod/v4").ZodObject<{
+            'x-continue-after': import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, false, false, {
+            200: import("zod/v4").ZodObject<{
+                items: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                    uniqueId: import("zod/v4").ZodString;
+                    groupId: import("zod/v4").ZodString;
+                    metadata: import("zod/v4").ZodRecord<import("zod/v4").ZodAny, import("zod/v4").ZodAny>;
+                }, import("zod/v4/core").$strip>>;
+                next: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+                hasMore: import("zod/v4").ZodOptional<import("zod/v4").ZodBoolean>;
+                nextCursor: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+            }, import("zod/v4/core").$strip>;
+        }>;
+        readonly postCacheItems: import("@lokalise/api-contracts").PayloadRouteDefinition<import("zod/v4").ZodObject<{
+            items: import("zod/v4").ZodOptional<import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                uniqueId: import("zod/v4").ZodString;
+                groupId: import("zod/v4").ZodString;
+                metadata: import("zod/v4").ZodRecord<import("zod/v4").ZodAny, import("zod/v4").ZodAny>;
+            }, import("zod/v4/core").$strip>>>;
+            maxItems: import("zod/v4").ZodOptional<import("zod/v4").ZodNumber>;
+            cursor: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, import("zod/v4").ZodObject<{
+            items: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                uniqueId: import("zod/v4").ZodString;
+                groupId: import("zod/v4").ZodString;
+                metadata: import("zod/v4").ZodRecord<import("zod/v4").ZodAny, import("zod/v4").ZodAny>;
+                fields: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+                title: import("zod/v4").ZodString;
+                groupTitle: import("zod/v4").ZodString;
+            }, import("zod/v4/core").$strip>>;
+            hasMore: import("zod/v4").ZodOptional<import("zod/v4").ZodBoolean>;
+            nextCursor: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, undefined, undefined, import("zod/v4").ZodObject<{
+            'ce-config': import("zod/v4").ZodString;
+            'ce-auth': import("zod/v4").ZodString;
+            "x-connector-id": import("zod/v4").ZodString;
+        }, import("zod/v4/core").$strip>, import("zod/v4").ZodObject<{
+            'x-continue-after': import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+        }, import("zod/v4/core").$strip>, false, false, {
+            200: import("zod/v4").ZodObject<{
+                items: import("zod/v4").ZodArray<import("zod/v4").ZodObject<{
+                    uniqueId: import("zod/v4").ZodString;
+                    groupId: import("zod/v4").ZodString;
+                    metadata: import("zod/v4").ZodRecord<import("zod/v4").ZodAny, import("zod/v4").ZodAny>;
+                    fields: import("zod/v4").ZodObject<{}, import("zod/v4/core").$loose>;
+                    title: import("zod/v4").ZodString;
+                    groupTitle: import("zod/v4").ZodString;
+                }, import("zod/v4/core").$strip>>;
+                hasMore: import("zod/v4").ZodOptional<import("zod/v4").ZodBoolean>;
+                nextCursor: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
+            }, import("zod/v4/core").$strip>;
+        }>;
+    };
+    private readonly adapters;
+    private readonly protectedRouteMetadataMapper;
+    constructor(dependencies: ConnectorShellDependencies);
+    private get getCache();
+    private get getCacheItems();
+    buildRoutes(): BuildRoutesReturnType<CacheControllerContractsType>;
+}
+export {};

package/dist/cache/cacheController.js

@@ -0,0 +1,74 @@
+import { EnhancedCacheFlowNotSupportedError, StandardCacheFlowNotSupportedError, } from '@lokalise/connector-adapter-common';
+import { CONNECTOR_ID_HEADER, getCacheContract, postCacheItemsContract, } from '@lokalise/connector-api-contracts';
+import { buildFastifyNoPayloadRoute, buildFastifyPayloadRoute, } from '@lokalise/fastify-api-contracts';
+import { AbstractController } from 'opinionated-machine';
+import { resolveAdapter } from "../adapterResolver/resolveAdapter.js";
+import "../commonTypes.js";
+export class CacheController extends AbstractController {
+    static contracts = {
+        getCache: getCacheContract,
+        postCacheItems: postCacheItemsContract,
+    };
+    adapters;
+    protectedRouteMetadataMapper;
+    constructor(dependencies) {
+        super();
+        this.adapters = dependencies.adapters;
+        this.protectedRouteMetadataMapper = dependencies.protectedRouteMetadataMapperFactory;
+    }
+    get getCache() {
+        return buildFastifyNoPayloadRoute(getCacheContract, async (req, reply) => {
+            const adapter = resolveAdapter(this.adapters, req.headers[CONNECTOR_ID_HEADER]);
+            if (!adapter.cacheService) {
+                throw new StandardCacheFlowNotSupportedError(adapter.getConnectorName());
+            }
+            const { items, nextCursor } = await adapter.cacheService.listItems(req.integrationConfig, req.authConfig, req.reqContext, req.query.next);
+            await reply.send({
+                items,
+                next: nextCursor,
+            });
+        }, this.protectedRouteMetadataMapper());
+    }
+    get getCacheItems() {
+        return buildFastifyPayloadRoute(postCacheItemsContract, async (req, reply) => {
+            const adapter = resolveAdapter(this.adapters, req.headers[CONNECTOR_ID_HEADER]);
+            /**
+             * postCacheItemsContract contract supports 2 cache refresh flows:
+             *   - Standard flow with IDs prefetching and passing item IDs in the request body.
+             *   - Enhanced flow without IDs prefetching, where item IDs are not passed in the request body,
+             *     instead cursor-based pagination is used.
+             *
+             * The decision what flow to use is made based on the presence of items in the request body.
+             */
+            const isEnhancedFlow = req.body.items === undefined;
+            if (isEnhancedFlow) {
+                // Enhanced flow: cursor-based pagination without ID prefetching
+                if (!adapter.cacheServiceEnhanced) {
+                    throw new EnhancedCacheFlowNotSupportedError(adapter.getConnectorName());
+                }
+                const result = await adapter.cacheServiceEnhanced.getItems(req.integrationConfig, req.authConfig, {
+                    cursor: req.body.cursor,
+                }, req.reqContext);
+                await reply.send(result);
+            }
+            else {
+                // Standard flow: with item IDs prefetching
+                if (!adapter.cacheService) {
+                    throw new StandardCacheFlowNotSupportedError(adapter.getConnectorName());
+                }
+                const items = await adapter.cacheService.getItems(req.integrationConfig, req.authConfig, req.body.items, // It's safe to assume that items are defined as we're in the standard flow
+                req.reqContext);
+                await reply.send({
+                    items,
+                });
+            }
+        }, this.protectedRouteMetadataMapper());
+    }
+    buildRoutes() {
+        return {
+            getCache: this.getCache,
+            postCacheItems: this.getCacheItems,
+        };
+    }
+}
+//# sourceMappingURL=cacheController.js.map

package/dist/cache/cacheController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheController.js","sourceRoot":"","sources":["../../src/cache/cacheController.ts"],"names":[],"mappings":"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"}