@livx.cc/native-kit 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Isomorphic native-capabilities kit for PWAs \u2014 same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -5,6 +5,7 @@ import type { KitModuleRegistry } from './module-registry';
 import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Platform, Unsubscribe } from './types';
 import { AppModule } from '../modules/app';
 import { AppleSignInModule } from '../modules/appleSignIn';
+import { ShareTargetModule } from '../modules/shareTarget';
 import { BackgroundTaskModule } from '../modules/backgroundTask';
 import { BiometricsModule } from '../modules/biometrics';
 import { BrowserModule } from '../modules/browser';
@@ -107,6 +108,7 @@ export class NativeKit {
   public readonly backgroundTask = new BackgroundTaskModule(this);
   public readonly tracking = new TrackingModule(this);
   public readonly appleSignIn = new AppleSignInModule(this);
+  public readonly shareTarget = new ShareTargetModule(this);
 
   /**
    * Additive, string-keyed registry mirroring the eager fields above (SAME instances) — a new
@@ -152,6 +154,7 @@ export class NativeKit {
       speech: this.speech, calendar: this.calendar, app: this.app, browser: this.browser,
       oauth: this.oauth, updates: this.updates,
       backgroundTask: this.backgroundTask, tracking: this.tracking, appleSignIn: this.appleSignIn,
+      shareTarget: this.shareTarget,
     };
     for (const [name, inst] of Object.entries(eager)) this.modules.registerModule(name, inst);
   }
@@ -378,6 +381,7 @@ declare module './module-registry' {
     backgroundTask: BackgroundTaskModule;
     tracking: TrackingModule;
     appleSignIn: AppleSignInModule;
+    shareTarget: ShareTargetModule;
   }
 }
 

package/src/core/module-registry.ts

@@ -43,8 +43,14 @@ export class ModuleRegistry {
     return [...new Set([...this.instances.keys(), ...this.factories.keys()])].sort();
   }
 
+  /**
+   * Typed, string-keyed lookup. STRICT by design: the ONLY public signature is keyed to
+   * `keyof KitModuleRegistry`, so `getModule('billing')` is a COMPILE ERROR unless the billing pack's
+   * kit client has been imported (its `declare module` augments the registry) — you get compile-time
+   * verification + autocomplete of exactly the modules you've wired, never a runtime surprise. For a
+   * genuinely dynamic name, use {@link getModuleUnsafe}.
+   */
   getModule<K extends keyof KitModuleRegistry>(name: K): KitModuleRegistry[K];
-  getModule<T = unknown>(name: string): T;
   getModule(name: string): unknown {
     if (this.instances.has(name)) return this.instances.get(name);
     const factory = this.factories.get(name);
@@ -61,4 +67,10 @@ export class ModuleRegistry {
         `Did you list its pack in modulePacks?`
     );
   }
+
+  /** Escape hatch for a genuinely DYNAMIC module name (not a compile-time literal) — bypasses the
+   * keyed check. Prefer {@link getModule}; reach for this only when the name isn't statically known. */
+  getModuleUnsafe<T = unknown>(name: string): T {
+    return (this.getModule as (n: string) => unknown)(name) as T;
+  }
 }

package/src/index.ts

@@ -53,4 +53,6 @@ export type {
 } from './modules/appleSignIn';
 export { isAppleSignInResult } from './modules/appleSignIn';
 export { BackgroundTaskModule } from './modules/backgroundTask';
+export { ShareTargetModule, parseSharePayload } from './modules/shareTarget';
+export type { SharedPayload } from './modules/shareTarget';
 export type { BackgroundTaskHandler, ScheduleBackgroundTaskOptions } from './modules/backgroundTask';

package/src/modules/shareTarget.ts

@@ -0,0 +1,93 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/** A payload shared INTO the app from the OS share sheet. */
+export interface SharedPayload {
+  /** Shared text / URL (Android EXTRA_TEXT). */
+  text?: string;
+  /** Share subject/title (Android EXTRA_SUBJECT), when the sender set one. */
+  title?: string;
+  /** Shared files (images), copied by the shell into the app cache — each entry is a path relative
+   * to the cache root, readable via `kit.fs.read(p, { dir: 'cache', encoding: 'base64' })`. */
+  files?: string[];
+}
+
+/**
+ * Parse a shareTarget deep link (`<scheme>://share?text=…&title=…&file=…&file=…`) into a payload.
+ * Returns null for any URL that isn't a share delivery — safe to feed every deep link through.
+ */
+export function parseSharePayload(url: string | null | undefined): SharedPayload | null {
+  // Custom-scheme `<scheme>://share?…` only — http(s) URLs are ordinary web links, never a share delivery.
+  if (!url || !/^(?!https?:)[a-z][a-z0-9.+-]*:\/\/share(\?|$)/i.test(url)) return null;
+  const q = new URLSearchParams(url.split('?')[1] ?? '');
+  const payload: SharedPayload = {};
+  const text = q.get('text');
+  if (text) payload.text = text;
+  const title = q.get('title');
+  if (title) payload.title = title;
+  const files = q.getAll('file');
+  if (files.length) payload.files = files;
+  return Object.keys(payload).length ? payload : null;
+}
+
+/**
+ * Inbound share-target (`shareTarget` module — opt-in): receive content shared TO the app from the
+ * OS share sheet. Delivery rides the deep-link path — the shell synthesizes
+ * `<urlScheme>://share?text=…&title=…&file=…` for both cold launches (handshake deep link) and warm
+ * shares (deeplink.open) — so this module is a thin typed parser over `kit.lifecycle`.
+ *
+ * Capability (honest): Android + iOS `'native'` — Android via an ACTION_SEND intent-filter on the
+ * main activity, iOS via a generated `AppwrapShare` share-extension target that forwards over the
+ * app's `urlScheme` (config REQUIRED) with images crossing through the App Group container; web
+ * `'none'` (no Web Share Target wiring).
+ */
+export class ShareTargetModule {
+  private launchConsumed = false;
+
+  constructor(private kit: NativeKit) {}
+
+  get capability() {
+    return this.kit.capability('shareTarget');
+  }
+
+  /**
+   * Subscribe to inbound shares. Fires for warm shares immediately; the COLD-START share (the app was
+   * launched by the share) is replayed once to the first subscriber after `kit.ready()` resolves —
+   * subscribe early (right after boot) to catch it.
+   */
+  /**
+   * Publish the app's SHARE CONTEXT — a small string KV the iOS share extension can read (App Group
+   * `appwrap-share-context`) to complete a share directly against the app's backend (the config's
+   * `shareTarget.directSync` lane resolves its `{key}` template placeholders from this KV). The
+   * framework treats the KV as opaque — publish whatever your sync endpoint needs (e.g. `{ binId }`)
+   * and re-publish whenever it changes. `null` clears it (direct sync falls back to the mailbox).
+   * Rejects (`UNSUPPORTED`) on the web / on shells that predate the method — treat it as
+   * fire-and-forget with a `.catch` (the mailbox path needs no context).
+   */
+  setContext(context: Record<string, string | number> | null): Promise<void> {
+    return this.kit.invoke('shareTarget.setContext', { context });
+  }
+
+  onReceive(cb: (payload: SharedPayload) => void): Unsubscribe {
+    let cancelled = false;
+    void this.kit
+      .ready()
+      .then(() => {
+        if (cancelled || this.launchConsumed) return;
+        const payload = parseSharePayload(this.kit.handshakeInfo?.deepLink);
+        if (payload) {
+          this.launchConsumed = true; // read-once: a second subscriber shouldn't re-ingest it
+          cb(payload);
+        }
+      })
+      .catch(() => { /* web/no-shell: no handshake, nothing to replay */ });
+    const un = this.kit.on('deeplink.open', (p) => {
+      const payload = parseSharePayload((p as { url: string }).url);
+      if (payload) cb(payload);
+    });
+    return () => {
+      cancelled = true;
+      un();
+    };
+  }
+}