@analyticscli/sdk 0.1.0-preview.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) AnalyticsCLI
+
+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,116 @@
+# @analyticscli/sdk
+
+TypeScript SDK for tenant developers sending onboarding, paywall, purchase, and survey analytics events to the AnalyticsCLI ingest API.
+
+Current npm release channel: preview / experimental beta.
+If no stable release exists yet, `latest` points to the newest preview.
+Once stable releases exist, `latest` is pinned to the newest stable.
+
+## Install
+
+```bash
+npm install @analyticscli/sdk@preview
+```
+
+When a stable release becomes available, install without a tag:
+
+```bash
+npm install @analyticscli/sdk
+```
+
+## Usage (Low Boilerplate)
+
+```ts
+import { init, ONBOARDING_EVENTS } from '@analyticscli/sdk';
+
+const analytics = init('<YOUR_APP_KEY>'); // short form
+
+analytics.trackOnboardingEvent(ONBOARDING_EVENTS.START, {
+  onboardingFlowId: 'onboarding_v1',
+});
+```
+
+`init(...)` accepts either:
+
+- `init('<YOUR_APP_KEY>')`
+- `init({ ...allOptionsOptional })`
+
+`initFromEnv()` remains available and resolves credentials from these env keys:
+
+- `ANALYTICSCLI_WRITE_KEY`
+- `NEXT_PUBLIC_ANALYTICSCLI_WRITE_KEY`
+- `EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY`
+- `VITE_ANALYTICSCLI_WRITE_KEY`
+
+Runtime-specific env helpers are also available:
+
+- `@analyticscli/sdk` -> `initBrowserFromEnv(...)`
+  - adds `PUBLIC_ANALYTICSCLI_WRITE_KEY` lookup for Astro/browser-first setups
+- `@analyticscli/sdk` -> `initReactNativeFromEnv(...)`
+  - defaults to native-friendly env key lookup
+- optional compatibility subpaths:
+  - `@analyticscli/sdk/browser`
+  - `@analyticscli/sdk/react-native`
+
+If config is missing, the client is a safe no-op (default behavior).
+When `apiKey` is missing, the SDK logs a console error and remains no-op.
+Use strict mode if you want hard failure:
+
+```ts
+const analytics = initFromEnv({
+  missingConfigMode: 'throw',
+});
+```
+
+## Optional Configuration
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import * as Application from 'expo-application';
+import { Platform } from 'react-native';
+import { init } from '@analyticscli/sdk';
+
+const analytics = init({
+  apiKey: process.env.EXPO_PUBLIC_ANALYTICSCLI_WRITE_KEY,
+  debug: typeof __DEV__ === 'boolean' ? __DEV__ : false,
+  platform:
+    Platform.OS === 'ios' ||
+    Platform.OS === 'android' ||
+    Platform.OS === 'windows' ||
+    Platform.OS === 'macos'
+      ? Platform.OS === 'macos'
+        ? 'mac'
+        : Platform.OS
+      : undefined,
+  appVersion: Application.nativeApplicationVersion ?? undefined,
+  dedupeOnboardingStepViewsPerSession: true,
+  storage: {
+    getItem: (key) => AsyncStorage.getItem(key),
+    setItem: (key, value) => AsyncStorage.setItem(key, value),
+    removeItem: (key) => AsyncStorage.removeItem(key),
+  },
+});
+
+void analytics.ready();
+```
+
+Use your project-specific write key from the AnalyticsCLI dashboard in your workspace.
+Only the write key (`apiKey`) is needed for SDK init calls.
+The SDK uses the default collector endpoint internally.
+In host apps, do not pass `endpoint` and do not add `ANALYTICSCLI_ENDPOINT` env vars.
+
+For browser subdomain continuity, set `cookieDomain` (for example `.analyticscli.com`).
+For redirects across different domains, use a backend-issued short-lived handoff token rather than relying on third-party cookies.
+
+## Releases
+
+Versioning is managed in the private monorepo via Changesets.
+Every SDK change should include a changeset entry (`pnpm changeset`), and CI creates
+the release version PR (`chore(release): version sdk-ts`) automatically on `main`.
+
+After that release PR is merged, the public mirror repository can run `Release to npm`.
+Each successful run creates or updates the matching GitHub Release
+(`v<package.json version>`) and links to the published npm version.
+
+Source of truth for this package is the private monorepo path `packages/sdk-ts`.
+Public mirror source prefix: `packages/sdk-ts`.