ink-framework-wallet 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandam Dinh
+
+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

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# Wallet pass previews
 
-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.
+`@ink/wallet` previews single `.pkpass` attachments on Android. `wallet.preview(source, signal)` accepts an HTTP(S) URL or an `ink-file://` managed file. Native code caches static previews by source, reusing the saved metadata and artwork before downloading or reading the ZIP. Missing artwork is rebuilt from the cached archive. Source keys are hashed, with up to eight source aliases per archive and 32 cached archives. `PassPreview` displays its fields and supported barcode using Ink components.
+
+```tsx
+const pass = await wallet.preview(attachment.src, signal);
+<PassPreview pass={pass} />
+if (await wallet.canOpen("com.vandamd.passes")) {
+  await wallet.open(pass, "com.vandamd.passes");
+}
+```
+
+Receiving apps implement an exported `com.vandam.ink.PassImportActivity`. The sender must declare the receiver package in Android `<queries>` for `canOpen`. The hand-off is an explicit `ACTION_VIEW` containing a FileProvider content URI, PKPass MIME type and temporary read permission. Copy the file while that permission is active. Passes implements this contract and asks the user before saving.
+
+Conversation rows use `filePreview: { title, label, artwork? }` and `onFilePress(message)` to reuse the native link-card layout without representing an attachment as a web link. Artwork appears in a 56 × 56 square beside the labels, preserving its aspect ratio. Beeper loads pass artwork in the background and leaves the text card usable if no artwork is available.
+
+Artwork: logo, strip, thumbnail, background, footer and icon PNGs, preferring @3x then @2x. Artwork is displayed as images alongside the fields, with background used when no strip is present. `wallet.retain(pass)` makes artwork durable before saving its returned metadata; `wallet.release(pass)` removes saved artwork when deleting a pass. Preview eviction does not remove retained artwork.
+
+Layout: pass field groups drive paired primary fields (with a transit arrow for boarding passes), paired details and a centred barcode with its `altText` caption. The decorative logo/title row is hidden to keep the ticket compact. Header fields remain visible as ordinary detail rows; an unlabelled boarding-pass header that repeats the displayed route is omitted. Back fields are available through Passes’ action menu’s Info page; Beeper hides them. `wallet.details(pass)` returns labelled text parts with link destinations, parsing HTML anchors and recognising plain web and email links. Render linked parts with `Text href` for underlined, tappable links. Older saved passes without group metadata retain all fields in paired rows; reimport to restore the original grouping.
+
+Supported: classic boarding pass, coupon, event ticket, generic and store card fields; QR, PDF417, Aztec and Code128 barcodes. UTF-8 is supported, along with ASCII data in recognised legacy encodings. Unsupported barcode formats or non-ASCII legacy encodings are omitted rather than silently changing the encoded data. Passes can still save the fields.
+
+This is a static preview, not a full Apple Wallet implementation: no signature verification, exact Wallet layout reproduction, localisation, live updates, NFC or multi-pass archives. Date and time styles use the device locale, respecting `ignoresTimeZone`; invalid dates retain their source text. Numbers retain their source values. Cached previews are regenerated when the parser version changes. See [Apple's pass format](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html).
+
+Limits: 10 MB per archive, 256 ZIP entries and 256 KB of `pass.json`, and 1 KB of barcode payload. Only the six recognised artwork filenames are read, with generated managed-file names. Each image is bounded to 2 MB, 4096 pixels per side and 8 megapixels. Only the 32 most recent archives remain in the preview cache; a missing cached archive requires reopening its preview. Passes stores the decoded fields/barcode separately, so a saved pass remains available offline.

package/ink-native.json

@@ -0,0 +1 @@
+{ "version": 1, "modules": { "src/index.tsx": ["files", "network", "file-images", "image"] } }

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "ink-framework-wallet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "exports": {
+    ".": "./src/index.tsx"
+  },
+  "dependencies": {
+    "valibot": "1.5.0"
+  },
+  "peerDependencies": {
+    "ink": "npm:ink-framework@0.1.0-alpha.1",
+    "react": "19.2.8",
+    "@ink/barcode": "npm:ink-framework-barcode@0.1.0-alpha.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/No-Scrolling/ink.git",
+    "directory": "packages/wallet"
+  },
+  "files": [
+    "src",
+    "*.json",
+    "*.ts"
+  ]
+}

package/src/index.tsx

@@ -0,0 +1,115 @@
+import * as v from "valibot";
+import { Icon, Image, Stack, Text } from "ink";
+import { arrowForward } from "ink/icons";
+import { callNative } from "ink/native";
+import { Barcode, supportedFormats } from "@ink/barcode";
+
+const artworkSchema = v.object({ src: v.string(), width: v.number(), height: v.number() });
+export const walletPassSchema = v.object({
+  id: v.string(),
+  serialNumber: v.string(),
+  passTypeIdentifier: v.string(),
+  title: v.string(),
+  organisation: v.string(),
+  description: v.string(),
+  artwork: v.optional(v.object({
+    logo: v.optional(artworkSchema), strip: v.optional(artworkSchema), thumbnail: v.optional(artworkSchema),
+    background: v.optional(artworkSchema), footer: v.optional(artworkSchema), icon: v.optional(artworkSchema),
+  })),
+  style: v.optional(v.string()),
+  fields: v.array(v.object({ label: v.string(), value: v.string(), group: v.optional(v.string()), displayValue: v.optional(v.string()) })),
+  barcode: v.optional(v.object({ format: v.picklist(supportedFormats), value: v.string(), altText: v.optional(v.string()) })),
+});
+const detailFieldsSchema = v.array(v.object({
+  label: v.string(),
+  parts: v.array(v.object({ text: v.string(), url: v.optional(v.string()) })),
+}));
+export type PassDetailField = v.InferOutput<typeof detailFieldsSchema>[number];
+export type WalletPass = v.InferOutput<typeof walletPassSchema>;
+
+export function isWalletPass(file: { name?: string; mimeType?: string; src?: string }) {
+  return file.mimeType?.split(";")[0].trim().toLowerCase() === "application/vnd.apple.pkpass"
+    || /\.pkpass(?:[?#]|$)/i.test(file.name || "")
+    || /\.pkpass(?:[?#]|$)/i.test(file.src || "");
+}
+
+export const wallet = {
+  async preview(source: string, signal?: AbortSignal): Promise<WalletPass> {
+    return v.parse(walletPassSchema, JSON.parse(await callNative("files", "pass-preview", { source }, { signal })));
+  },
+  async details(pass: WalletPass): Promise<PassDetailField[]> {
+    return v.parse(detailFieldsSchema, JSON.parse(await callNative("files", "pass-details", { pass })));
+  },
+  async retain(pass: WalletPass): Promise<WalletPass> {
+    return v.parse(walletPassSchema, JSON.parse(await callNative("files", "pass-retain", { pass })));
+  },
+  async release(pass: WalletPass): Promise<void> {
+    for (const image of Object.values(pass.artwork || {})) {
+      if (image?.src.startsWith(`ink-file://${pass.id}-s-`))
+        await callNative("files", "remove", { id: image.src.slice("ink-file://".length) });
+    }
+  },
+  async canOpen(packageName: string): Promise<boolean> {
+    return await callNative("files", "pass-can-open", { packageName }) === "true";
+  },
+  async open(pass: WalletPass, packageName: string): Promise<void> {
+    await callNative("files", "pass-open", { id: pass.id, packageName });
+  },
+};
+
+function Artwork({ image, width = 300, fillWidth = false }: { image?: v.InferOutput<typeof artworkSchema>; width?: number; fillWidth?: boolean }) {
+  if (!image) return null;
+  if (fillWidth) return <Image src={image.src} width={image.width} height={image.height} fillWidth fit="contain" />;
+  width = Math.min(width, image.width);
+  const height = Math.min(200, width * image.height / image.width);
+  return <Image src={image.src} width={width} height={height} fit="contain" />;
+}
+
+type PassField = WalletPass["fields"][number];
+function Field({ field, primary = false, paired = false, end = false }: { field: PassField; primary?: boolean; paired?: boolean; end?: boolean }) {
+  return <Stack gap={0} align={end ? "end" : "start"}>
+    {field.label && <Text size={11} width={primary && paired ? 140 : undefined} align={end ? "end" : "start"}>{field.label.toUpperCase()}</Text>}
+    <Text size={primary ? 36 : 16} width={primary && paired ? 140 : undefined} align={end ? "end" : "start"}>{field.displayValue ?? field.value}</Text>
+  </Stack>;
+}
+function FieldRows({ fields, primary = false, transit = false }: { fields: PassField[]; primary?: boolean; transit?: boolean }) {
+  const rows = [];
+  for (let index = 0; index < fields.length; index += 2) {
+    rows.push(<Stack key={index} axis="horizontal" justify="space-between" align="center" gap={6}>
+      <Field field={fields[index]} primary={primary} paired={!!fields[index + 1]} />
+      {transit && index === 0 && fields[index + 1] && <Icon name={arrowForward} size={24} />}
+      {fields[index + 1] && <Field field={fields[index + 1]} primary={primary} paired end />}
+    </Stack>);
+  }
+  return <Stack gap={14} align="stretch">{rows}</Stack>;
+}
+function routeText(value: string) {
+  return value.replace(/\s+/g, "").replace(/[–—→]/g, "-").toUpperCase();
+}
+
+export function PassPreview({ pass }: { pass: WalletPass }) {
+  const artwork = pass.artwork;
+  const fields = pass.fields.filter(field => field.label.trim() || field.value.trim());
+  const primary = fields.filter(field => field.group === "primaryFields");
+  const secondary = fields.filter(field => field.group === "secondaryFields" || !field.group);
+  const route = pass.style === "boardingPass" && primary.length === 2
+    ? routeText(`${primary[0].value}-${primary[1].value}`) : undefined;
+  const headers = fields.filter(field => field.group === "headerFields"
+    && !(route && !field.label.trim() && routeText(field.value.replace(/^[^:]*:/, "")) === route));
+  const auxiliary = fields.filter(field => field.group === "auxiliaryFields");
+  return <Stack gap={14} align="stretch" justify="space-between">
+    <Stack gap={14} align="stretch">
+      <Artwork image={artwork?.strip || artwork?.background} fillWidth />
+      <Artwork image={artwork?.thumbnail} width={80} />
+      {primary.length > 0 && <FieldRows fields={primary} primary transit={pass.style === "boardingPass"} />}
+      {(pass.style === "boardingPass" ? [auxiliary, secondary] : [secondary, auxiliary]).map((fields, index) =>
+        fields.length > 0 && <FieldRows key={index} fields={fields} />)}
+      {headers.length > 0 && <FieldRows fields={headers} />}
+      <Artwork image={artwork?.footer} />
+    </Stack>
+    {pass.barcode ? <Stack align="center" gap={5}>
+      <Barcode format={pass.barcode.format} value={pass.barcode.value} size={200} />
+      {pass.barcode.altText && <Text size={14} align="center">{pass.barcode.altText}</Text>}
+    </Stack> : <Text>This pass has no supported barcode.</Text>}
+  </Stack>;
+}