dtunnel-sdk 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 DTunnel0
+
+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,144 @@
+# DTunnel SDK
+
+SDK JavaScript/TypeScript para consumir a bridge Android (`window.Dt...`) usada no WebView do DTunnel.
+
+Inclui:
+- wrappers dos objetos nativos (`sdk.config`, `sdk.main`, `sdk.text`, `sdk.app`, `sdk.android`)
+- eventos nativos com API semantica (`sdk.on('vpnState', ...)`)
+- tipagem completa para TypeScript
+- helper para React em `dtunnel-sdk/react`
+
+## Instalacao (npm)
+
+```bash
+npm install dtunnel-sdk
+```
+
+## Uso com TypeScript
+
+```ts
+import DTunnelSDK from 'dtunnel-sdk';
+
+const sdk = new DTunnelSDK({
+  strict: false,
+  autoRegisterNativeEvents: true,
+});
+
+sdk.on('vpnState', (event) => {
+  console.log(event.payload);
+});
+```
+
+## Uso com React + TypeScript
+
+```tsx
+import { DTunnelSDKProvider, useDTunnelEvent } from 'dtunnel-sdk/react';
+
+function VpnStateLabel() {
+  useDTunnelEvent('vpnState', (event) => {
+    console.log('VPN:', event.payload);
+  });
+
+  return <span>Escutando eventos...</span>;
+}
+
+export function App() {
+  return (
+    <DTunnelSDKProvider options={{ strict: false }}>
+      <VpnStateLabel />
+    </DTunnelSDKProvider>
+  );
+}
+```
+
+## Uso via script (CDN)
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/DTunnel0/DTunnelSDK@main/sdk/dtunnel-sdk.js"></script>
+<script>
+  const sdk = new DTunnelSDK({ strict: false, autoRegisterNativeEvents: true });
+</script>
+```
+
+## Eventos semanticos
+
+- `vpnState`
+- `vpnStartedSuccess`
+- `vpnStoppedSuccess`
+- `newLog`
+- `configClick`
+- `checkUserStarted`
+- `checkUserResult`
+- `checkUserError`
+- `messageError`
+- `showSuccessToast`
+- `showErrorToast`
+- `notification`
+
+## Estrutura principal
+
+- runtime CJS/global: `sdk/dtunnel-sdk.js`
+- runtime ESM: `sdk/dtunnel-sdk.mjs`
+- tipos TS: `sdk/dtunnel-sdk.d.ts`
+- helpers React: `react/index.js`, `react/index.mjs`, `react/index.d.ts`
+- exemplos completos: `examples/`
+
+## Exemplos completos
+
+- CDN (JavaScript puro): `examples/cdn/index.html`
+- TypeScript (Vite): `examples/typescript`
+- React + TypeScript (Vite): `examples/react-typescript`
+- Guia geral: `examples/README.md`
+
+### Regra para WebView
+
+Sempre gere/entregue **um unico `index.html`** com todo CSS/JS embutido para carregar no WebView.
+
+- CDN: `examples/cdn/index.html` ja atende esse formato.
+- TypeScript e React + TypeScript: rode `npm run build:webview` no exemplo para gerar `webview/index.html`.
+- Atalho na raiz para gerar ambos: `npm run examples:webview`.
+
+Guia rapido:
+
+```bash
+# TypeScript
+cd examples/typescript
+npm install
+npm run dev
+```
+
+```bash
+# React + TypeScript
+cd examples/react-typescript
+npm install
+npm run dev
+```
+
+## Publicacao de release
+
+Com o repositorio limpo e commitado:
+
+```bash
+npm run release:sdk -- --version 1.1.0
+```
+
+## Publicacao no npm
+
+Scripts de release/publicacao sao cross-platform (Linux, macOS e Windows) via Node.js.
+
+```bash
+npm login
+npm run publish:npm
+```
+
+Opcional (tag diferente de `latest`):
+
+```bash
+npm run publish:npm -- --tag next
+```
+
+Dry-run:
+
+```bash
+npm run publish:npm:dry
+```

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dtunnel-sdk",
+  "version": "1.1.0",
+  "description": "JavaScript/TypeScript SDK for the DTunnel Android WebView bridge.",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "./sdk/dtunnel-sdk.js",
+  "module": "./sdk/dtunnel-sdk.mjs",
+  "types": "./sdk/dtunnel-sdk.d.ts",
+  "scripts": {
+    "examples:webview": "npm --prefix examples/typescript run build:webview && npm --prefix examples/react-typescript run build:webview",
+    "publish:npm": "node ./scripts/publish-npm.mjs",
+    "publish:npm:dry": "node ./scripts/publish-npm.mjs --dry-run --skip-auth",
+    "release:sdk": "node ./scripts/release-sdk.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./sdk/dtunnel-sdk.d.ts",
+      "import": "./sdk/dtunnel-sdk.mjs",
+      "require": "./sdk/dtunnel-sdk.js",
+      "default": "./sdk/dtunnel-sdk.js"
+    },
+    "./react": {
+      "types": "./react/index.d.ts",
+      "import": "./react/index.mjs",
+      "require": "./react/index.js",
+      "default": "./react/index.js"
+    },
+    "./sdk/dtunnel-sdk.js": "./sdk/dtunnel-sdk.js",
+    "./sdk/dtunnel-sdk.d.ts": "./sdk/dtunnel-sdk.d.ts"
+  },
+  "files": [
+    "sdk",
+    "react",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dtunnel",
+    "sdk",
+    "webview",
+    "android",
+    "vpn",
+    "typescript",
+    "react"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DTunnel0/DTunnelSDK.git"
+  }
+}

package/react/index.d.ts

@@ -0,0 +1,64 @@
+import type { Context, ReactElement, ReactNode } from 'react';
+import type {
+  DTunnelAnyNativeEventEnvelope,
+  DTunnelAnySemanticEventEnvelope,
+  DTunnelCallbackName,
+  DTunnelErrorEvent,
+  DTunnelNativeEventByCallback,
+  DTunnelSDK,
+  DTunnelSDKOptions,
+  DTunnelSemanticEventEnvelope,
+  DTunnelSemanticEventName,
+} from '../sdk/dtunnel-sdk';
+
+export interface DTunnelSDKProviderProps {
+  children?: ReactNode;
+  sdk?: DTunnelSDK;
+  options?: DTunnelSDKOptions;
+}
+
+export declare const DTunnelSDKContext: Context<DTunnelSDK | null>;
+
+export declare function DTunnelSDKProvider(
+  props: DTunnelSDKProviderProps,
+): ReactElement;
+
+export declare function useDTunnelSDK(): DTunnelSDK;
+
+export declare function useDTunnelEvent<E extends DTunnelSemanticEventName>(
+  eventName: E,
+  listener: (event: DTunnelSemanticEventEnvelope<E>) => void,
+): void;
+
+export declare function useDTunnelEvent(
+  eventName: 'nativeEvent',
+  listener: (event: DTunnelAnySemanticEventEnvelope) => void,
+): void;
+
+export declare function useDTunnelEvent<E extends DTunnelCallbackName>(
+  eventName: `native:${E}`,
+  listener: (event: DTunnelNativeEventByCallback<E>) => void,
+): void;
+
+export declare function useDTunnelEvent(
+  eventName: `native:${string}`,
+  listener: (event: DTunnelAnyNativeEventEnvelope) => void,
+): void;
+
+export declare function useDTunnelEvent(
+  eventName: 'error',
+  listener: (event: DTunnelErrorEvent) => void,
+): void;
+
+export declare function useDTunnelEvent(
+  eventName: string,
+  listener: (event: unknown) => void,
+): void;
+
+export declare function useDTunnelNativeEvent(
+  listener: (event: DTunnelAnySemanticEventEnvelope) => void,
+): void;
+
+export declare function useDTunnelError(
+  listener: (event: DTunnelErrorEvent) => void,
+): void;

package/react/index.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const React = require('react');
+const sdkModule = require('../sdk/dtunnel-sdk.js');
+
+const DTunnelSDK =
+  (sdkModule && (sdkModule.DTunnelSDK || sdkModule.default)) ||
+  (typeof globalThis !== 'undefined' ? globalThis.DTunnelSDK : undefined);
+
+if (typeof DTunnelSDK !== 'function') {
+  throw new Error(
+    'DTunnelSDK nao foi encontrado. Importe "dtunnel-sdk" antes de usar "dtunnel-sdk/react".',
+  );
+}
+
+const DTunnelSDKContext = React.createContext(null);
+
+function DTunnelSDKProvider(props) {
+  const sdk = props.sdk || null;
+  const options = props.options || {};
+  const children = props.children;
+
+  const createdSdkRef = React.useRef(null);
+
+  if (!sdk && !createdSdkRef.current) {
+    createdSdkRef.current = new DTunnelSDK(options);
+  }
+
+  const value = sdk || createdSdkRef.current;
+
+  React.useEffect(() => {
+    if (sdk) return undefined;
+
+    return () => {
+      if (
+        createdSdkRef.current &&
+        typeof createdSdkRef.current.destroy === 'function'
+      ) {
+        createdSdkRef.current.destroy();
+      }
+    };
+  }, [sdk]);
+
+  return React.createElement(DTunnelSDKContext.Provider, { value }, children);
+}
+
+function useDTunnelSDK() {
+  const sdk = React.useContext(DTunnelSDKContext);
+  if (!sdk) {
+    throw new Error('useDTunnelSDK precisa estar dentro de <DTunnelSDKProvider>.');
+  }
+  return sdk;
+}
+
+function useDTunnelEvent(eventName, listener) {
+  const sdk = useDTunnelSDK();
+  const listenerRef = React.useRef(listener);
+
+  React.useEffect(() => {
+    listenerRef.current = listener;
+  }, [listener]);
+
+  React.useEffect(() => {
+    const unsubscribe = sdk.on(eventName, (event) => {
+      listenerRef.current(event);
+    });
+    return unsubscribe;
+  }, [sdk, eventName]);
+}
+
+function useDTunnelNativeEvent(listener) {
+  useDTunnelEvent('nativeEvent', listener);
+}
+
+function useDTunnelError(listener) {
+  useDTunnelEvent('error', listener);
+}
+
+module.exports = {
+  DTunnelSDKContext,
+  DTunnelSDKProvider,
+  useDTunnelSDK,
+  useDTunnelEvent,
+  useDTunnelNativeEvent,
+  useDTunnelError,
+};

package/react/index.mjs

@@ -0,0 +1,80 @@
+import React, { createContext, useContext, useEffect, useRef } from 'react';
+import { DTunnelSDK } from '../sdk/dtunnel-sdk.mjs';
+
+if (typeof DTunnelSDK !== 'function') {
+  throw new Error(
+    'DTunnelSDK nao foi encontrado. Importe "dtunnel-sdk" antes de usar "dtunnel-sdk/react".',
+  );
+}
+
+const DTunnelSDKContext = createContext(null);
+
+function DTunnelSDKProvider(props) {
+  const sdk = props.sdk ?? null;
+  const options = props.options ?? {};
+  const children = props.children;
+
+  const createdSdkRef = useRef(null);
+
+  if (!sdk && !createdSdkRef.current) {
+    createdSdkRef.current = new DTunnelSDK(options);
+  }
+
+  const value = sdk ?? createdSdkRef.current;
+
+  useEffect(() => {
+    if (sdk) return undefined;
+
+    return () => {
+      if (
+        createdSdkRef.current &&
+        typeof createdSdkRef.current.destroy === 'function'
+      ) {
+        createdSdkRef.current.destroy();
+      }
+    };
+  }, [sdk]);
+
+  return React.createElement(DTunnelSDKContext.Provider, { value }, children);
+}
+
+function useDTunnelSDK() {
+  const sdk = useContext(DTunnelSDKContext);
+  if (!sdk) {
+    throw new Error('useDTunnelSDK precisa estar dentro de <DTunnelSDKProvider>.');
+  }
+  return sdk;
+}
+
+function useDTunnelEvent(eventName, listener) {
+  const sdk = useDTunnelSDK();
+  const listenerRef = useRef(listener);
+
+  useEffect(() => {
+    listenerRef.current = listener;
+  }, [listener]);
+
+  useEffect(() => {
+    const unsubscribe = sdk.on(eventName, (event) => {
+      listenerRef.current(event);
+    });
+    return unsubscribe;
+  }, [sdk, eventName]);
+}
+
+function useDTunnelNativeEvent(listener) {
+  useDTunnelEvent('nativeEvent', listener);
+}
+
+function useDTunnelError(listener) {
+  useDTunnelEvent('error', listener);
+}
+
+export {
+  DTunnelSDKContext,
+  DTunnelSDKProvider,
+  useDTunnelSDK,
+  useDTunnelEvent,
+  useDTunnelNativeEvent,
+  useDTunnelError,
+};

package/sdk/README.md

@@ -0,0 +1,65 @@
+# DTunnel SDK (Runtime)
+
+Arquivos do runtime e tipagem:
+
+- `dtunnel-sdk.js`: build principal (script tag + CommonJS)
+- `dtunnel-sdk.mjs`: entrada ESM para bundlers
+- `dtunnel-sdk.d.ts`: tipagem TypeScript
+
+## Inicializacao
+
+```ts
+import DTunnelSDK from 'dtunnel-sdk';
+
+const sdk = new DTunnelSDK({
+  strict: false,
+  autoRegisterNativeEvents: true,
+});
+```
+
+## Modulos
+
+- `sdk.config`
+- `sdk.main`
+- `sdk.text`
+- `sdk.app`
+- `sdk.android`
+
+## Eventos
+
+Use `sdk.on('<evento>', handler)` com:
+
+- `vpnState`
+- `vpnStartedSuccess`
+- `vpnStoppedSuccess`
+- `newLog`
+- `configClick`
+- `checkUserStarted`
+- `checkUserResult`
+- `checkUserError`
+- `messageError`
+- `showSuccessToast`
+- `showErrorToast`
+- `notification`
+
+## Erros
+
+- `strict: true`: lanca excecao (`DTunnelBridgeError`)
+- `strict: false`: retorna `null` e publica evento `error`
+
+## Exemplos completos
+
+- CDN: `examples/cdn/index.html`
+- TypeScript: `examples/typescript`
+- React + TypeScript: `examples/react-typescript`
+- Guia geral: `examples/README.md`
+
+Regra para WebView:
+- entregue sempre um unico `index.html` com CSS/JS embutido.
+- nos exemplos TypeScript/React, use `npm run build:webview` para gerar `webview/index.html`.
+- atalho na raiz: `npm run examples:webview`.
+
+Publicacao npm (raiz do repo):
+- scripts de publicacao/release sao cross-platform (Linux, macOS e Windows).
+- `npm login`
+- `npm run publish:npm`