@livx.cc/native-kit 0.43.0 → 0.44.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.43.0",
-  "description": "Isomorphic native-capabilities kit for PWAs \u2014 same API in browser and in an appwrap native shell. Zero dependencies.",
+  "version": "0.44.1",
+  "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",
   "homepage": "https://github.com/Livshitz/appwrap#readme",

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,11 +108,12 @@ 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
    * capability-access path out-of-repo module packs register into (e.g. the billing/health/widget
-   * EE packs call `kit.modules.registerModule(...)`). For core modules `kit.getModule('haptics')
+   * out-of-tree packs call `kit.modules.registerModule(...)`). For core modules `kit.getModule('haptics')
    * === kit.haptics`. Fails loud on miss.
    */
   public readonly modules = new ModuleRegistry();
@@ -140,7 +142,7 @@ export class NativeKit {
     this.options = { ...new NativeKitOptions(), ...options };
     // Mirror the eager CORE fields into the string-keyed registry (same instances, no behaviour
     // change). Typed as a plain string map — not `Record<keyof KitModuleRegistry, unknown>` — because
-    // out-of-repo packs augment KitModuleRegistry with keys CE never mounts (billing/health/widget);
+    // out-of-repo packs augment KitModuleRegistry with keys the core never mounts (billing/health/widget);
     // those are registered by the pack's register<Name>Kit(), not here.
     const eager: Record<string, unknown> = {
       haptics: this.haptics, share: this.share, screen: this.screen, keyboard: this.keyboard,
@@ -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/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/notifications.ts

@@ -30,6 +30,12 @@ export interface ScheduleOptions {
    * badge unchanged. Set 0 to clear on delivery.
    */
   badge?: number;
+  /**
+   * Deliver WITHOUT the alert sound. Default (omitted/false) plays the system alert sound on
+   * both platforms — a scheduled notification is an alert, and a silent one is almost never
+   * what the caller meant. Android honours this on API 29+ only.
+   */
+  silent?: boolean;
 }
 
 export class NotificationsModule {

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();
+    };
+  }
+}