feat(sdk): port deprecation warning and @deprecated JSDoc to dev (#2252)

* feat(core): warn once per process that SelfBackendVerifier is deprecated

* fix(core): share deprecation-warn sentinel across ESM/CJS bundles

* fix(ci): include generated typechain types in the core-sdk build cache

* feat(sdk): add @deprecated JSDoc to legacy Self Pass SDK exports

* fix(qrcode-angular): tag SelfQRcodeComponent as deprecated

---------

Co-authored-by: kartikmehta8 <kartik.mehta@self.xyz>

Author: kartikmehta8

.github/actions/cache-core-sdk-build/action.yml

@@ -8,7 +8,7 @@ inputs:
   cache-version:
     description: Cache version string
     required: false
-    default: v1
+    default: v2
   fail-on-cache-miss:
     description: Fail if cache not found (restore mode only)
     required: false
@@ -29,6 +29,7 @@ runs:
         path: |
           common/dist
           sdk/core/dist
+          sdk/core/src/typechain-types
         key: core-sdk-build-${{ inputs.cache-version }}-${{ github.sha }}
         fail-on-cache-miss: ${{ inputs.fail-on-cache-miss }}
     - id: save
@@ -38,4 +39,5 @@ runs:
         path: |
           common/dist
           sdk/core/dist
+          sdk/core/src/typechain-types
         key: core-sdk-build-${{ inputs.cache-version }}-${{ github.sha }}

.github/workflows/core-sdk-ci.yml

@@ -73,7 +73,7 @@ jobs:
         uses: ./.github/actions/cache-core-sdk-build
         with:
           mode: save
-          cache-version: v1
+          cache-version: v2
 
   lint:
     runs-on: ubuntu-latest
@@ -90,7 +90,7 @@ jobs:
         uses: ./.github/actions/cache-core-sdk-build
         with:
           mode: restore
-          cache-version: v1
+          cache-version: v2
           fail-on-cache-miss: false
       - name: Install Dependencies
         uses: ./.github/actions/pnpm-install
@@ -117,7 +117,7 @@ jobs:
         uses: ./.github/actions/cache-core-sdk-build
         with:
           mode: restore
-          cache-version: v1
+          cache-version: v2
           fail-on-cache-miss: false
       - name: Install Dependencies
         uses: ./.github/actions/pnpm-install
@@ -144,7 +144,7 @@ jobs:
         uses: ./.github/actions/cache-core-sdk-build
         with:
           mode: restore
-          cache-version: v1
+          cache-version: v2
           fail-on-cache-miss: false
       - name: Install Dependencies
         uses: ./.github/actions/pnpm-install

common/src/utils/appType.ts

@@ -49,6 +49,12 @@ export interface SelfAppDisclosureConfig {
   minimumAge?: number;
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk`: create a session with `SelfClient` and redirect the user
+ * to the hosted `verificationUrl` instead of building a Self app config.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export class SelfAppBuilder {
   private config: SelfApp;
 
@@ -126,6 +132,12 @@ export class SelfAppBuilder {
   }
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk` and redirect the user to the hosted `verificationUrl`
+ * returned by `SelfClient` instead of constructing a universal link.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export function getUniversalLink(selfApp: SelfApp): string {
   return `${REDIRECT_URL}?selfApp=${encodeURIComponent(JSON.stringify(selfApp))}`;
 }

sdk/core/src/SelfBackendVerifier.ts

@@ -33,6 +33,13 @@ const CELO_TESTNET_RPC_URL = 'https://forno.celo-sepolia.celo-testnet.org';
 const IDENTITY_VERIFICATION_HUB_ADDRESS = '0xe57F4773bd9c9d8b6Cd70431117d353298B9f5BF';
 const IDENTITY_VERIFICATION_HUB_ADDRESS_STAGING = '0x16ECBA51e18a4a7e61fdC417f0d47AFEeDfbed74';
 
+const DEPRECATION_WARNED_KEY = Symbol.for('selfxyz.core.deprecation-warned');
+
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `SelfClient` from `@selfxyz/enterprise-sdk` — the managed verifier replaces this class.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export class SelfBackendVerifier {
   protected scope: string;
   protected identityVerificationHubContract: IdentityVerificationHubImpl;
@@ -49,6 +56,12 @@ export class SelfBackendVerifier {
     configStorage: IConfigStorage,
     userIdentifierType: UserIdType
   ) {
+    if (!(globalThis as Record<symbol, unknown>)[DEPRECATION_WARNED_KEY]) {
+      (globalThis as Record<symbol, unknown>)[DEPRECATION_WARNED_KEY] = true;
+      console.warn(
+        '[@selfxyz/core] SelfBackendVerifier is deprecated — new integrations must use @selfxyz/enterprise-sdk. Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/'
+      );
+    }
     const rpcUrl = mockPassport ? CELO_TESTNET_RPC_URL : CELO_MAINNET_RPC_URL;
     const provider = new ethers.JsonRpcProvider(rpcUrl);
     const identityVerificationHubAddress = mockPassport

sdk/core/tests/deprecationWarning.test.ts

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { SelfBackendVerifier } from '../src/SelfBackendVerifier.js';
+import { AttestationId } from '../src/types/types.js';
+
+const configStorage = {
+  getConfig: async () => ({ olderThan: 18, excludedCountries: [], ofac: false }),
+  getActionId: async () => 'test',
+  setConfig: async () => false,
+};
+
+const construct = () =>
+  new SelfBackendVerifier(
+    'test-scope',
+    'https://example.com/api/verify',
+    true,
+    new Map<AttestationId, boolean>([[1, true]]),
+    configStorage,
+    'uuid'
+  );
+
+test('constructor warns about deprecation exactly once per process', () => {
+  const warnings: string[] = [];
+  const originalWarn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(' '));
+  };
+  try {
+    construct();
+    construct();
+  } finally {
+    console.warn = originalWarn;
+  }
+
+  const deprecationWarnings = warnings.filter((w) => w.includes('deprecated'));
+  assert.equal(deprecationWarnings.length, 1);
+  assert.ok(deprecationWarnings[0].includes('@selfxyz/enterprise-sdk'));
+  assert.ok(
+    deprecationWarnings[0].includes(
+      'https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/'
+    )
+  );
+});

sdk/qrcode-angular/src/lib/common.ts

@@ -567,6 +567,12 @@ export function validateUserId(userId: string, type: UserIdType): boolean {
   }
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk`: create a session with `SelfClient` and redirect the user
+ * to the hosted `verificationUrl` instead of building a Self app config.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export class SelfAppBuilder {
   private config: SelfApp;
 
@@ -643,6 +649,12 @@ export class SelfAppBuilder {
   }
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk` and redirect the user to the hosted `verificationUrl`
+ * returned by `SelfClient` instead of constructing a universal link.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export function getUniversalLink(selfApp: SelfApp): string {
   return `${REDIRECT_URL}?selfApp=${encodeURIComponent(JSON.stringify(selfApp))}`;
 }

sdk/qrcode-angular/src/lib/components/self-qrcode/self-qrcode.component.ts

@@ -30,6 +30,12 @@ export interface SelfQRcodeProps {
   darkMode?: boolean;
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk`: redirect the user to the hosted `verificationUrl` —
+ * you no longer render your own QR code.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 @Component({
   selector: 'lib-self-qrcode',
   standalone: true,

sdk/qrcode/components/SelfQRcode.tsx

@@ -28,6 +28,12 @@ interface SelfQRcodeProps {
   variant?: 'hybrid' | 'desktop' | 'mobile';
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk`: redirect the user to the hosted `verificationUrl` —
+ * you no longer render your own QR code.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 const SelfQRcodeWrapper = (props: SelfQRcodeProps) => {
   const [isClient, setIsClient] = useState(false);
   useEffect(() => {
@@ -40,6 +46,12 @@ const SelfQRcodeWrapper = (props: SelfQRcodeProps) => {
   return <SelfQRcode {...props} />;
 };
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk`: redirect the user to the hosted `verificationUrl` —
+ * you no longer render your own QR code.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 const SelfQRcode = ({
   selfApp,
   onSuccess,

sdk/sdk-common/index.ts

@@ -567,6 +567,12 @@ export function validateUserId(userId: string, type: UserIdType): boolean {
   }
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk`: create a session with `SelfClient` and redirect the user
+ * to the hosted `verificationUrl` instead of building a Self app config.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export class SelfAppBuilder {
   private config: SelfApp;
 
@@ -643,6 +649,12 @@ export class SelfAppBuilder {
   }
 }
 
+/**
+ * @deprecated The open-source Self Pass SDK is legacy. New integrations must use
+ * `@selfxyz/enterprise-sdk` and redirect the user to the hosted `verificationUrl`
+ * returned by `SelfClient` instead of constructing a universal link.
+ * Migration guide: https://docs.self.xyz/docs/self-enterprise/migration/from-self-pass-sdk/
+ */
 export function getUniversalLink(selfApp: SelfApp): string {
   return `${REDIRECT_URL}?selfApp=${encodeURIComponent(JSON.stringify(selfApp))}`;
 }