@straitlink/capacitor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Strait authors
+
+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/Package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+// @straitlink/capacitor, iOS side: a thin Capacitor plugin over StraitSDK (Swift Package Manager).
+let package = Package(
+    name: "StraitlinkCapacitor",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(name: "StraitlinkCapacitor", targets: ["StraitPlugin"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
+        .package(url: "https://github.com/strait-link/strait-sdk-swift.git", from: "0.9.3"),
+    ],
+    targets: [
+        .target(
+            name: "StraitPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "StraitSDK", package: "strait-sdk-swift"),
+            ],
+            path: "ios/Sources/StraitPlugin"
+        ),
+    ]
+)

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+<!-- Header: the same in every Strait SDK README (design system v5). -->
+<p align="center">
+  <a href="https://straitlink.in">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset=".github/assets/strait-lockup-dark.svg">
+      <img src=".github/assets/strait-lockup.svg" alt="Strait" width="160" height="53">
+    </picture>
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Strait SDK for Capacitor and Ionic</h1>
+
+<p align="center"><strong>Straight to the screen. On the record.</strong><br>
+A tap opens the exact screen, and every link open and install is recorded in your Strait dashboard.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@straitlink/capacitor"><img alt="npm" src="https://img.shields.io/npm/v/@straitlink/capacitor?style=flat-square&labelColor=0F0D0A&color=423B33"></a>
+  <a href="https://straitlink.in/platform-status/"><img alt="SDK: New" src="https://img.shields.io/badge/SDK-new-423B33?style=flat-square&labelColor=0F0D0A"></a>
+  <a href="https://github.com/strait-link/strait-sdk-capacitor/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/strait-link/strait-sdk-capacitor/ci.yml?branch=main&label=CI&style=flat-square&labelColor=0F0D0A"></a>
+  <a href="LICENSE"><img alt="Licence: MIT" src="https://img.shields.io/badge/licence-MIT-423B33?style=flat-square&labelColor=0F0D0A"></a>
+</p>
+
+<p align="center">
+  <a href="https://straitlink.in/docs/sdks/capacitor/">Docs</a> ·
+  <a href="https://straitlink.in/platform-status/">Platform status</a> ·
+  <a href="CHANGELOG.md">Changelog</a> ·
+  <a href="#docs-and-support">Talk to the Strait team</a>
+</p>
+
+`@straitlink/capacitor` gives a Capacitor 8 app (Ionic, Vue, React, Angular or plain JS) direct
+links (App Links, Universal Links, custom schemes), deferred links that survive the install, and
+link-open analytics. It wraps the Strait [Android](https://github.com/strait-link/strait-sdk-android)
+and [iOS](https://github.com/strait-link/strait-sdk-swift) SDKs, and its API matches
+[`@straitlink/react-native`](https://github.com/strait-link/strait-sdk-react-native).
+
+## Quick start (60 seconds)
+
+You need: a Capacitor 8 app with `android/` and/or `ios/` added, and from
+**Dashboard → Get started** your publishable key (`st_pub_live_…`) and link domain
+(`https://<your-handle>.strait.link`).
+
+**1. Install and sync**
+
+```sh
+npm install @straitlink/capacitor
+npx cap sync
+```
+
+**2. Start it when your app starts** (for example in `main.ts`)
+
+```ts
+import { createStrait } from '@straitlink/capacitor';
+
+const strait = createStrait({
+  publishableKey: 'st_pub_live_…',            // safe in apps; never the secret key
+  endpoint: 'https://<your-handle>.strait.link',
+});
+strait.onLink((e) => {
+  console.log('Strait link:', e.kind, e.route, e.matched, e.path);
+  if (e.matched && e.path) router.push({ path: e.path, query: e.params }); // your router
+});
+strait.start();
+```
+
+**3. Let the app claim your link domain**
+
+- Android, `android/app/src/main/AndroidManifest.xml`, inside the main `<activity>`:
+
+  ```xml
+  <intent-filter android:autoVerify="true">
+      <action android:name="android.intent.action.VIEW" />
+      <category android:name="android.intent.category.DEFAULT" />
+      <category android:name="android.intent.category.BROWSABLE" />
+      <data android:scheme="https" android:host="<your-handle>.strait.link" />
+  </intent-filter>
+  ```
+
+- iOS, Xcode → App target → Signing & Capabilities → **+ Associated Domains** →
+  `applinks:<your-handle>.strait.link`.
+- In **Dashboard → Settings → App**: your Android package name + signing SHA-256, and your
+  Apple Team ID + bundle ID. Strait then serves `assetlinks.json` and the
+  `apple-app-site-association` file for you.
+
+**You should see:** run the app on a phone or emulator, then open one of your links:
+
+```sh
+adb shell am start -a android.intent.action.VIEW -d "https://<your-handle>.strait.link/<code>"
+xcrun simctl openurl booted "https://<your-handle>.strait.link/<code>"
+```
+
+The app opens on the link's screen and the console prints
+`Strait link: direct app_link true /p/42` (your path). The open shows up in the dashboard's
+Analytics within a minute. On a fresh install the first launch prints a `deferred` event instead.
+
+## Platform features
+
+| Feature | Status | Notes |
+|---|---|---|
+| Android: direct links and deferred links | ● Live | Deferred = exact match through the Play Install Referrer (read for you). |
+| iPhone links (Universal Links, custom schemes) | ● Live | Through Capacitor's AppDelegate / SceneDelegate proxy: no extra code. |
+| iPhone: install matching (deferred links) | Opt-in | Your choice in Dashboard → Settings → iPhone installs, read at runtime. See the [iOS SDK](https://github.com/strait-link/strait-sdk-swift#iphone-you-choose-the-deferred-link-method). |
+| iOS with CocoaPods | – Not yet | Swift Package Manager only (the Capacitor 8 default for new apps). |
+| Web | – | Every call resolves a safe default; use [`@straitlink/web`](https://www.npmjs.com/package/@straitlink/web) for websites. |
+| Published on npm | ● Live | `npm install @straitlink/capacitor` |
+
+● Live · Opt-in: off until you switch it on · – Not yet. The same words as the
+[platform status](https://straitlink.in/platform-status/) page.
+
+## API
+
+| Call | What it does |
+|---|---|
+| `createStrait({ publishableKey, endpoint, linkHosts? })` | One client per app. Throws only for a missing or secret key. `linkHosts` adds custom short-link hosts or old `<x>.page.link` hosts. |
+| `start()` | Reads the link that launched the app, listens for new ones, runs the deferred check once per install, sends saved open reports. Call it once, after `onLink`. |
+| `onLink(cb)` | Every link event, including ones from before you subscribed. Returns an unsubscribe. |
+| `onLinkStart(cb)` | A link just arrived and is being resolved: show a loading state. |
+| `checkDeferred()` | Asks for the deferred link again (settings or debug screens). Doesn't add an install. |
+| `trackEvent(name, { value, currency, linkId, clickId })` | Conversion or revenue event, placed on the tap of the last attributed open (7 days). Resolves `true` when accepted. |
+| `pendingOpenReports()` / `flushOpenReports()` | Open reports saved while offline (sent again on start and resume). |
+| `deviceClass()` | `phone` or `tablet` (iPad / 600 dp and up), as sent with open reports. |
+| `stop()` | Stops delivering events to this object. |
+
+`LinkEvent`: `id, kind (direct|deferred), route (app_link|custom_scheme|install_referrer|fingerprint|clipboard),
+appState (closed|background|foreground), matched, reason, rawUrl, url, path, params, linkId, referralCode, ms, at`.
+After `createStrait`, nothing throws: a failure resolves `matched: false` with a `reason`, `false`, `0` or nothing.
+
+## How it works
+
+The plugin is a thin layer. All link logic (resolving short links, the once-per-install deferred
+check, open reports and their retry queue, app-state labels) runs in the native SDKs, which share
+golden test vectors with the Strait engine:
+
+- **Android:** `strait-sdk-android` **v0.8.1** from JitPack. The plugin adds JitPack to your Gradle
+  repositories, limited to the `com.github.strait-link` group, so nothing else is ever fetched from
+  it. It reads the Play Install Referrer (`com.android.installreferrer:installreferrer:2.2`), the launch
+  intent and `onNewIntent`, and keeps state in SharedPreferences (`strait`).
+- **iOS:** `StraitSDK` **0.9.3+** through Swift Package Manager. Links come from Capacitor's
+  `capacitorOpenURL` / `capacitorOpenUniversalLink` notifications; state lives in `UserDefaults`.
+
+What gets recorded, the privacy details and the match methods are the same as the native SDKs:
+see [Android](https://github.com/strait-link/strait-sdk-android#what-strait-records-automatically-no-extra-code)
+and [iOS](https://github.com/strait-link/strait-sdk-swift#what-strait-records-automatically-no-extra-code).
+
+### Testing a deferred link on an Android emulator
+
+A sideloaded app never gets a Play Install Referrer. **Debug builds only** accept a stand-in on the
+first launch after install (release builds ignore it):
+
+```sh
+adb shell am start -n <your.package>/.MainActivity \
+  --es strait.debugReferrer "'strait_link=lnk_…&strait_click=…'"
+```
+
+Take both values from the Play Store URL your link redirects an Android phone to (its `referrer=`).
+
+## Sample app
+
+[`examples/capacitor-app`](examples/capacitor-app): a plain-JS Capacitor app with two screens
+(Home and Product), a "Check deferred link" button and a "Log a purchase" button. CI builds it for
+Android and the iOS Simulator on every pull request.
+
+```sh
+cd examples/capacitor-app && npm install
+STRAIT_PUBLISHABLE_KEY=st_pub_live_… STRAIT_ENDPOINT=https://<your-handle>.strait.link npm run sync
+npx cap run android    # or: npx cap run ios
+```
+
+## Docs and support
+
+- **Docs:** [straitlink.in/docs/sdks/capacitor/](https://straitlink.in/docs/sdks/capacitor/) · [platform status](https://straitlink.in/platform-status/) · [troubleshooting](https://straitlink.in/docs/troubleshooting/)
+- **Talk to the Strait team:** [support@straitlink.in](mailto:support@straitlink.in) (replies within 1 working day, IST) or call +91 81218 61890.
+- **Bugs and feature requests:** [open an issue](https://github.com/strait-link/strait-sdk-capacitor/issues) on this repo.
+- **Security:** never in a public issue. Write to security@straitlink.in (see [SECURITY.md](SECURITY.md)).

package/android/build.gradle

@@ -0,0 +1,56 @@
+// @straitlink/capacitor, Android side: a thin Capacitor plugin over strait-sdk-android (JitPack).
+ext {
+    straitSdkVersion = 'v0.8.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+// strait-sdk-android is built by JitPack from its version tags. Gradle resolves this plugin's
+// dependencies with the app's repositories, so add JitPack to every project, limited to the
+// Strait group (nothing else is ever fetched from JitPack).
+rootProject.allprojects {
+    repositories {
+        maven {
+            url 'https://jitpack.io'
+            content { includeGroup 'com.github.strait-link' }
+        }
+    }
+}
+
+android {
+    namespace = 'dev.strait.capacitor'
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    lint {
+        abortOnError = false
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:${project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'}"
+    implementation "com.github.strait-link:strait-sdk-android:${straitSdkVersion}"
+    implementation 'com.android.installreferrer:installreferrer:2.2'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/dev/strait/capacitor/StraitPlugin.java

@@ -0,0 +1,280 @@
+package dev.strait.capacitor;
+
+import android.content.Context;
+import android.content.Intent;
+import android.content.SharedPreferences;
+import android.content.pm.ApplicationInfo;
+import android.util.DisplayMetrics;
+
+import com.android.installreferrer.api.InstallReferrerClient;
+import com.android.installreferrer.api.InstallReferrerStateListener;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.TimeZone;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+
+import dev.strait.sdk.AppLifecycleState;
+import dev.strait.sdk.CoreKt;
+import dev.strait.sdk.DeviceFields;
+import dev.strait.sdk.KeyValueStore;
+import dev.strait.sdk.LinkEvent;
+import dev.strait.sdk.LinkStart;
+import dev.strait.sdk.StraitClient;
+import dev.strait.sdk.StraitConfig;
+import dev.strait.sdk.UrlConnectionTransport;
+import kotlin.Unit;
+
+/**
+ * Capacitor bridge over strait-sdk-android's StraitClient. All link logic (resolve, deferred
+ * check once per install, open reports, retry queue) lives in the native SDK; this class only
+ * wires Android pieces (SharedPreferences, Play Install Referrer, display metrics, intents,
+ * lifecycle) and forwards events to JS as "link" / "linkStart".
+ */
+@CapacitorPlugin(name = "Strait")
+public class StraitPlugin extends Plugin {
+    private final ExecutorService executor = Executors.newSingleThreadExecutor();
+    private StraitClient client;
+    /** A link that arrived (onNewIntent) before JS called start(). */
+    private String pendingUrl;
+
+    @PluginMethod
+    public synchronized void start(PluginCall call) {
+        if (client != null) { // a WebView reload calls start() again: keep the one client
+            call.resolve();
+            return;
+        }
+        String key = call.getString("publishableKey", "");
+        String endpoint = call.getString("endpoint", "");
+        if (key == null || !key.startsWith("st_pub_") || endpoint == null || endpoint.isEmpty()) {
+            call.reject("Strait: start needs publishableKey (st_pub_...) and endpoint");
+            return;
+        }
+        List<String> hosts = new ArrayList<>();
+        JSArray arr = call.getArray("linkHosts", new JSArray());
+        for (int i = 0; i < arr.length(); i++) {
+            String h = arr.optString(i, null);
+            if (h != null && !h.isEmpty()) hosts.add(h);
+        }
+        Context ctx = getContext().getApplicationContext();
+        SharedPreferences prefs = ctx.getSharedPreferences("strait", Context.MODE_PRIVATE);
+        KeyValueStore storage = new KeyValueStore() {
+            @Override public String get(String k) { return prefs.getString(k, null); }
+            @Override public void set(String k, String v) { prefs.edit().putString(k, v).apply(); }
+        };
+        Intent launch = getActivity() != null ? getActivity().getIntent() : null;
+        String debugReferrer = debugReferrer(ctx, launch);
+        client = new StraitClient(new StraitConfig(
+            key,
+            endpoint,
+            hosts,
+            storage,
+            () -> debugReferrer != null ? debugReferrer : readInstallReferrer(ctx),
+            "android",
+            () -> device(ctx),
+            new UrlConnectionTransport(10_000, 10_000),
+            executor,
+            System::currentTimeMillis,
+            deviceClass(ctx)
+        ));
+        client.onLinkStart(s -> { notifyListeners("linkStart", toJs(s), true); return Unit.INSTANCE; });
+        client.onLink(e -> { notifyListeners("link", toJs(e), true); return Unit.INSTANCE; });
+        client.onAppState(AppLifecycleState.ACTIVE, System.currentTimeMillis());
+
+        String initial = pendingUrl != null ? pendingUrl : launchUrl(launch);
+        pendingUrl = null;
+        client.start(initial);
+        executor.execute(call::resolve); // after start's work on the same single thread
+    }
+
+    @PluginMethod
+    public void checkDeferred(PluginCall call) {
+        StraitClient c = ready(call);
+        if (c == null) return;
+        executor.execute(() -> call.resolve(toJs(c.checkDeferred())));
+    }
+
+    @PluginMethod
+    public void trackEvent(PluginCall call) {
+        StraitClient c = ready(call);
+        if (c == null) return;
+        String name = call.getString("name", "");
+        if (name == null || name.isEmpty()) {
+            call.reject("Strait: trackEvent needs a name");
+            return;
+        }
+        Double value = call.getDouble("value");
+        String currency = call.getString("currency");
+        String linkId = call.getString("linkId");
+        String clickId = call.getString("clickId");
+        executor.execute(() -> {
+            JSObject r = new JSObject();
+            r.put("accepted", c.trackEvent(name, value, currency, linkId, clickId));
+            call.resolve(r);
+        });
+    }
+
+    @PluginMethod
+    public void pendingOpenReports(PluginCall call) {
+        StraitClient c = ready(call);
+        if (c == null) return;
+        JSObject r = new JSObject();
+        r.put("count", c.pendingOpenReports());
+        call.resolve(r);
+    }
+
+    @PluginMethod
+    public void flushOpenReports(PluginCall call) {
+        StraitClient c = ready(call);
+        if (c == null) return;
+        executor.execute(() -> { c.flushOpenReports(); call.resolve(); });
+    }
+
+    @PluginMethod
+    public void deviceClass(PluginCall call) {
+        JSObject r = new JSObject();
+        String dc = deviceClass(getContext());
+        if (dc != null) r.put("deviceClass", dc);
+        call.resolve(r);
+    }
+
+    @Override
+    protected void handleOnNewIntent(Intent intent) {
+        super.handleOnNewIntent(intent);
+        String url = launchUrl(intent);
+        if (url == null) return;
+        synchronized (this) {
+            if (client == null) pendingUrl = url;
+            else client.handleUrl(url);
+        }
+    }
+
+    @Override
+    protected void handleOnResume() {
+        super.handleOnResume();
+        if (client != null) client.onAppState(AppLifecycleState.ACTIVE, System.currentTimeMillis());
+    }
+
+    @Override
+    protected void handleOnPause() {
+        super.handleOnPause();
+        if (client != null) client.onAppState(AppLifecycleState.INACTIVE, System.currentTimeMillis());
+    }
+
+    @Override
+    protected void handleOnStop() {
+        super.handleOnStop();
+        if (client != null) client.onAppState(AppLifecycleState.BACKGROUND, System.currentTimeMillis());
+    }
+
+    private StraitClient ready(PluginCall call) {
+        if (client == null) call.reject("Strait: call start() first");
+        return client;
+    }
+
+    /** The link in a VIEW intent, but not when Android replays an old intent from the recents screen. */
+    private static String launchUrl(Intent intent) {
+        if (intent == null || !Intent.ACTION_VIEW.equals(intent.getAction())) return null;
+        if ((intent.getFlags() & Intent.FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY) != 0) return null;
+        String s = intent.getDataString();
+        return s == null || s.isEmpty() ? null : s;
+    }
+
+    /**
+     * Debug builds only: a stand-in for the Play Install Referrer, so the deferred path can be tested
+     * on an emulator (a sideloaded app never gets a Play referrer). Release builds ignore it.
+     *   adb shell am start -n <package>/.MainActivity --es strait.debugReferrer "strait_link=lnk_…&strait_click=…"
+     */
+    private static String debugReferrer(Context ctx, Intent intent) {
+        if (intent == null || (ctx.getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE) == 0) return null;
+        String r = intent.getStringExtra("strait.debugReferrer");
+        return r == null || r.isEmpty() ? null : r;
+    }
+
+    private static DeviceFields device(Context ctx) {
+        DisplayMetrics m = ctx.getResources().getDisplayMetrics();
+        return new DeviceFields(
+            CoreKt.portraitScreenWidth(m.widthPixels / (double) m.density, m.heightPixels / (double) m.density),
+            m.density,
+            Locale.getDefault().toLanguageTag(),
+            TimeZone.getDefault().getID()
+        );
+    }
+
+    /** Contract B14: the sw600dp rule (600 dp or more = tablet). */
+    private static String deviceClass(Context ctx) {
+        return CoreKt.deviceClassForSize(ctx.getResources().getConfiguration().smallestScreenWidthDp);
+    }
+
+    /** Blocking read of the Play Install Referrer (runs on the SDK's executor), or null. */
+    private static String readInstallReferrer(Context ctx) {
+        CountDownLatch latch = new CountDownLatch(1);
+        String[] result = {null};
+        InstallReferrerClient rc = InstallReferrerClient.newBuilder(ctx).build();
+        try {
+            rc.startConnection(new InstallReferrerStateListener() {
+                @Override public void onInstallReferrerSetupFinished(int code) {
+                    if (code == InstallReferrerClient.InstallReferrerResponse.OK) {
+                        try { result[0] = rc.getInstallReferrer().getInstallReferrer(); } catch (Exception ignored) { }
+                    }
+                    latch.countDown();
+                }
+                @Override public void onInstallReferrerServiceDisconnected() { latch.countDown(); }
+            });
+            latch.await(5, TimeUnit.SECONDS);
+        } catch (Exception ignored) {
+        } finally {
+            try { rc.endConnection(); } catch (Exception ignored) { }
+        }
+        return result[0];
+    }
+
+    static JSObject toJs(LinkEvent e) {
+        JSObject o = new JSObject();
+        o.put("id", e.getId());
+        o.put("kind", e.getKind());
+        o.put("route", e.getRoute());
+        o.put("appState", e.getAppState());
+        o.put("matched", e.getMatched());
+        putIf(o, "reason", e.getReason());
+        putIf(o, "rawUrl", e.getRawUrl());
+        putIf(o, "url", e.getUrl());
+        putIf(o, "path", e.getPath());
+        putIf(o, "linkId", e.getLinkId());
+        putIf(o, "referralCode", e.getReferralCode());
+        Map<String, String> params = e.getParams();
+        if (params != null) {
+            JSObject p = new JSObject();
+            for (Map.Entry<String, String> kv : params.entrySet()) p.put(kv.getKey(), kv.getValue());
+            o.put("params", p);
+        }
+        o.put("ms", e.getMs());
+        o.put("at", e.getAt());
+        return o;
+    }
+
+    static JSObject toJs(LinkStart s) {
+        JSObject o = new JSObject();
+        o.put("id", s.getId());
+        o.put("kind", s.getKind());
+        o.put("appState", s.getAppState());
+        putIf(o, "rawUrl", s.getRawUrl());
+        o.put("at", s.getAt());
+        return o;
+    }
+
+    private static void putIf(JSObject o, String k, String v) {
+        if (v != null) o.put(k, v);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { type CreateStraitConfig, type Strait, type StraitNativePlugin } from './strait.js';
+/** The native plugin (registered as "Strait"). Most apps use `createStrait` instead. */
+export declare const StraitNative: StraitNativePlugin;
+/**
+ * Create one client when the app starts, subscribe with `onLink`, then call `start()`.
+ * Android and iOS only; on the web every call resolves a safe default (use @straitlink/web there).
+ */
+export declare function createStrait(config: CreateStraitConfig, native?: StraitNativePlugin): Strait;
+export type { CreateStraitConfig, DeviceClass, LinkEvent, LinkStart, Strait, StraitNativePlugin, TrackEventExtra, } from './strait.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+import { registerPlugin } from '@capacitor/core';
+import { createStrait as createWith } from './strait.js';
+/** The native plugin (registered as "Strait"). Most apps use `createStrait` instead. */
+export const StraitNative = registerPlugin('Strait');
+/**
+ * Create one client when the app starts, subscribe with `onLink`, then call `start()`.
+ * Android and iOS only; on the web every call resolves a safe default (use @straitlink/web there).
+ */
+export function createStrait(config, native = StraitNative) {
+    return createWith(config, native);
+}

package/dist/strait.d.ts

@@ -0,0 +1,94 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+/** One link the app received (B9): the same shape as @straitlink/react-native. */
+export interface LinkEvent {
+    /** Unique per open; also the id Strait records this open under. */
+    id: string;
+    /** direct = the app was opened by a link; deferred = link tapped before install. */
+    kind: 'direct' | 'deferred';
+    /** app_link · custom_scheme · install_referrer · fingerprint · clipboard. */
+    route: 'app_link' | 'custom_scheme' | 'install_referrer' | 'fingerprint' | 'clipboard';
+    /** What the app was doing when the link arrived. */
+    appState: 'closed' | 'background' | 'foreground';
+    matched: boolean;
+    /** Why it didn't match: not_found, expired, password_protected, network, no_match, unavailable, … */
+    reason?: string;
+    /** The URL the OS gave the app (direct links). */
+    rawUrl?: string;
+    /** The destination to navigate to. */
+    url?: string;
+    path?: string;
+    params?: Record<string, string>;
+    linkId?: string;
+    /** Deferred links only: the referral code the tap carried (preview, B21). */
+    referralCode?: string;
+    /** Time spent resolving, ms. */
+    ms: number;
+    at: number;
+}
+/** A link just arrived and is being resolved: show a loading state until the LinkEvent with the same id. */
+export interface LinkStart {
+    id: string;
+    kind: 'direct' | 'deferred';
+    appState: 'closed' | 'background' | 'foreground';
+    rawUrl?: string;
+    at: number;
+}
+export type DeviceClass = 'phone' | 'tablet';
+export interface CreateStraitConfig {
+    /** Your workspace's publishable key (`st_pub_live_…`), Dashboard → Get started. Never the secret key. */
+    publishableKey: string;
+    /** Your workspace's link domain, e.g. https://<your-handle>.strait.link */
+    endpoint: string;
+    /** Extra hosts that serve your short links (custom domains, old `<x>.page.link`). */
+    linkHosts?: string[];
+}
+export interface TrackEventExtra {
+    value?: number;
+    currency?: string;
+    linkId?: string;
+    clickId?: string;
+}
+/** The native side (Android: StraitPlugin.java over strait-sdk-android; iOS: StraitPlugin.swift over StraitSDK). */
+export interface StraitNativePlugin {
+    start(options: {
+        publishableKey: string;
+        endpoint: string;
+        linkHosts: string[];
+    }): Promise<void>;
+    checkDeferred(): Promise<LinkEvent>;
+    trackEvent(options: {
+        name: string;
+    } & TrackEventExtra): Promise<{
+        accepted: boolean;
+    }>;
+    pendingOpenReports(): Promise<{
+        count: number;
+    }>;
+    flushOpenReports(): Promise<void>;
+    deviceClass(): Promise<{
+        deviceClass?: DeviceClass;
+    }>;
+    addListener(event: 'link', cb: (e: LinkEvent) => void): Promise<PluginListenerHandle>;
+    addListener(event: 'linkStart', cb: (s: LinkStart) => void): Promise<PluginListenerHandle>;
+}
+export interface Strait {
+    /** Reads the launch link, listens for new ones, runs the deferred check once per install. */
+    start(): Promise<void>;
+    /** Every link event, including ones that happened before you subscribed. Returns an unsubscribe. */
+    onLink(cb: (event: LinkEvent) => void): () => void;
+    /** A link just arrived and is being resolved (for a loading state). Returns an unsubscribe. */
+    onLinkStart(cb: (start: LinkStart) => void): () => void;
+    /** Re-run the deferred check now (debugging); doesn't touch the once-per-install flag. */
+    checkDeferred(): Promise<LinkEvent>;
+    /** Conversion / revenue event, on the tap of the last attributed open (≤7 days, B15). True when accepted. */
+    trackEvent(name: string, extra?: TrackEventExtra): Promise<boolean>;
+    /** Open reports saved while offline, waiting to be sent (debugging). */
+    pendingOpenReports(): Promise<number>;
+    /** Send saved open reports now (also happens on start and on resume). */
+    flushOpenReports(): Promise<void>;
+    /** What the app runs on, as sent with open reports (B14): iPad / sw600dp = tablet. */
+    deviceClass(): Promise<DeviceClass | undefined>;
+    /** Stop delivering events to this object. */
+    stop(): void;
+}
+export declare function createStrait(config: CreateStraitConfig, native: StraitNativePlugin): Strait;

package/dist/strait.js

@@ -0,0 +1,69 @@
+export function createStrait(config, native) {
+    const key = config.publishableKey ?? '';
+    if (!key.startsWith('st_pub_')) {
+        throw new TypeError('Strait: use your publishable key (st_pub_…, Dashboard → Get started). A secret key must never ship inside an app.');
+    }
+    const events = [];
+    const linkCbs = new Set();
+    const startCbs = new Set();
+    const each = (cbs, x) => {
+        for (const cb of [...cbs]) {
+            try {
+                cb(x);
+            }
+            catch {
+                // an app's handler must not stop the others
+            }
+        }
+    };
+    // Subscribe before start(), so the link that launched the app is never missed.
+    const handles = [
+        native.addListener('link', (e) => {
+            events.push(e);
+            each(linkCbs, e);
+        }),
+        native.addListener('linkStart', (s) => each(startCbs, s)),
+    ];
+    let started;
+    const safe = async (fn, fallback) => {
+        try {
+            return await fn();
+        }
+        catch {
+            return fallback;
+        }
+    };
+    return {
+        start() {
+            started ??= safe(async () => {
+                await Promise.all(handles);
+                await native.start({ publishableKey: key, endpoint: config.endpoint, linkHosts: config.linkHosts ?? [] });
+            }, undefined);
+            return started;
+        },
+        onLink(cb) {
+            linkCbs.add(cb);
+            for (const e of [...events])
+                each(new Set([cb]), e);
+            return () => linkCbs.delete(cb);
+        },
+        onLinkStart(cb) {
+            startCbs.add(cb);
+            return () => startCbs.delete(cb);
+        },
+        checkDeferred: () => safe(() => native.checkDeferred(), {
+            id: '', kind: 'deferred', route: 'fingerprint', appState: 'foreground',
+            matched: false, reason: 'unavailable', ms: 0, at: Date.now(),
+        }),
+        trackEvent: (name, extra = {}) => safe(async () => (await native.trackEvent({ name, ...extra })).accepted === true, false),
+        pendingOpenReports: () => safe(async () => (await native.pendingOpenReports()).count ?? 0, 0),
+        flushOpenReports: () => safe(() => native.flushOpenReports(), undefined),
+        deviceClass: () => safe(async () => (await native.deviceClass()).deviceClass, undefined),
+        stop() {
+            linkCbs.clear();
+            startCbs.clear();
+            for (const h of handles)
+                void h.then((x) => x.remove()).catch(() => { });
+        },
+    };
+}

package/ios/Sources/StraitPlugin/StraitPlugin.swift

@@ -0,0 +1,129 @@
+import Foundation
+import Capacitor
+import StraitSDK
+
+/// Capacitor bridge over StraitSDK's `StraitLinks`. All link logic (resolve, deferred check once
+/// per install, open reports, retry queue, app-state labels) lives in the native SDK; this class
+/// only feeds it the links Capacitor's AppDelegate proxy receives and forwards events to JS as
+/// "link" / "linkStart".
+@objc(StraitPlugin)
+public class StraitPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "StraitPlugin"
+    public let jsName = "Strait"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "start", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "checkDeferred", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "trackEvent", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "pendingOpenReports", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "flushOpenReports", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "deviceClass", returnType: CAPPluginReturnPromise),
+    ]
+
+    private var links: StraitLinks?
+    private var subscriptions: [StraitSubscription] = []
+    /// A link that arrived before JS called start().
+    private var pendingURL: URL?
+
+    override public func load() {
+        for name in [Notification.Name.capacitorOpenURL, .capacitorOpenUniversalLink] {
+            NotificationCenter.default.addObserver(self, selector: #selector(onOpen(_:)), name: name, object: nil)
+        }
+    }
+
+    @objc private func onOpen(_ note: Notification) {
+        guard let url = (note.object as? [String: Any])?["url"] as? URL else { return }
+        DispatchQueue.main.async { [self] in
+            if let links = links { links.handle(url: url) } else { pendingURL = url }
+        }
+    }
+
+    @objc func start(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [self] in
+            if links != nil { call.resolve(); return } // a WebView reload calls start() again
+            let key = call.getString("publishableKey") ?? ""
+            let endpoint = call.getString("endpoint") ?? ""
+            guard key.hasPrefix("st_pub_"), !endpoint.isEmpty else {
+                call.reject("Strait: start needs publishableKey (st_pub_...) and endpoint")
+                return
+            }
+            let hosts = (call.getArray("linkHosts") as? [String]) ?? []
+            let l = StraitLinks(StraitLinksConfig(publishableKey: key, endpoint: endpoint, linkHosts: hosts))
+            links = l
+            subscriptions = [
+                l.onLinkStart { [weak self] s in self?.notifyListeners("linkStart", data: Self.js(s), retainUntilConsumed: true) },
+                l.onLink { [weak self] e in self?.notifyListeners("link", data: Self.js(e), retainUntilConsumed: true) },
+            ]
+            // The launch link: delivered before start() (cold start), or remembered by Capacitor.
+            let initial = pendingURL ?? ApplicationDelegateProxy.shared.lastURL
+            pendingURL = nil
+            l.start(initialURL: initial) { call.resolve() }
+        }
+    }
+
+    @objc func checkDeferred(_ call: CAPPluginCall) {
+        guard let l = ready(call) else { return }
+        l.checkDeferred { e in call.resolve(Self.js(e)) }
+    }
+
+    @objc func trackEvent(_ call: CAPPluginCall) {
+        guard let l = ready(call) else { return }
+        guard let name = call.getString("name"), !name.isEmpty else {
+            call.reject("Strait: trackEvent needs a name")
+            return
+        }
+        l.trackEvent(
+            name,
+            value: call.getDouble("value"),
+            currency: call.getString("currency"),
+            linkId: call.getString("linkId"),
+            clickId: call.getString("clickId")
+        ) { ok in call.resolve(["accepted": ok]) }
+    }
+
+    @objc func pendingOpenReports(_ call: CAPPluginCall) {
+        guard let l = ready(call) else { return }
+        l.pendingOpenReports { n in call.resolve(["count": n]) }
+    }
+
+    @objc func flushOpenReports(_ call: CAPPluginCall) {
+        guard let l = ready(call) else { return }
+        l.flushOpenReports { call.resolve() }
+    }
+
+    @objc func deviceClass(_ call: CAPPluginCall) {
+        DispatchQueue.main.async {
+            var r: [String: Any] = [:]
+            if let dc = currentDeviceClass() { r["deviceClass"] = dc }
+            call.resolve(r)
+        }
+    }
+
+    private func ready(_ call: CAPPluginCall) -> StraitLinks? {
+        guard let l = links else {
+            call.reject("Strait: call start() first")
+            return nil
+        }
+        return l
+    }
+
+    static func js(_ e: LinkEvent) -> [String: Any] {
+        var o: [String: Any] = [
+            "id": e.id, "kind": e.kind.rawValue, "route": e.route.rawValue, "appState": e.appState.rawValue,
+            "matched": e.matched, "ms": e.ms, "at": e.at,
+        ]
+        if let v = e.reason { o["reason"] = v }
+        if let v = e.rawUrl { o["rawUrl"] = v }
+        if let v = e.url { o["url"] = v }
+        if let v = e.path { o["path"] = v }
+        if let v = e.params { o["params"] = v }
+        if let v = e.linkId { o["linkId"] = v }
+        if let v = e.referralCode { o["referralCode"] = v }
+        return o
+    }
+
+    static func js(_ s: LinkStart) -> [String: Any] {
+        var o: [String: Any] = ["id": s.id, "kind": s.kind.rawValue, "appState": s.appState.rawValue, "at": s.at]
+        if let v = s.rawUrl { o["rawUrl"] = v }
+        return o
+    }
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@straitlink/capacitor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Deep linking for Capacitor and Ionic apps: direct links (App Links, Universal Links, custom schemes), deferred links that survive the install and link-open analytics. Wraps the Strait Android and iOS SDKs.",
+  "keywords": [
+    "capacitor",
+    "capacitor-plugin",
+    "ionic",
+    "deep-linking",
+    "deferred-deep-linking",
+    "universal-links",
+    "app-links",
+    "dynamic-links"
+  ],
+  "license": "MIT",
+  "author": "The Strait authors",
+  "homepage": "https://straitlink.in/docs/sdks/capacitor/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/strait-link/strait-sdk-capacitor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/strait-link/strait-sdk-capacitor/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "android/src/main/",
+    "android/build.gradle",
+    "ios/Sources",
+    "Package.swift"
+  ],
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@capacitor/core": ">=8.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@capacitor/core": "8.5.3",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.12"
+  }
+}