@pinet/transport-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+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,47 @@
+# @pinet/transport-core
+
+Tiny transport-neutral contracts package for the `extensions` repo.
+
+## What lives here
+
+- canonical `InboundMessage` contract
+- canonical `OutboundMessage` contract
+- normalized outbound `content` shape for transport-aware rendering with plain-text fallback
+- canonical `MessageAdapter` transport interface
+
+## What stays out of scope
+
+- broker state
+- routing
+- socket server/client logic
+- Slack-specific normalization
+- iMessage-specific AppleScript or readiness logic
+- Pi extension commands/tools
+
+This package exists to keep transport contracts transport-neutral while other packages decide how to route, persist, or render those messages.
+
+## Publishing
+
+This package is part of the full npm publish set tracked in
+[`../plans/npm-publish.md`](../plans/npm-publish.md). Use the GitHub Actions
+workflow's default dry-run/readiness path for validation; do not publish, tag, or
+bump versions without explicit maintainer release approval.
+
+## Outbound content rules
+
+`OutboundMessage.text` remains the backward-compatible plain-text fallback and persistence body.
+
+When richer transport-aware rendering is available, callers may also send `OutboundMessage.content`:
+
+- `content.text`: canonical plain-text body
+- `content.markdown`: optional markdown-friendly representation for markdown-capable text renderers or exports
+- `content.slackBlocks`: optional prebuilt Slack Block Kit payload
+
+Transports should prefer their transport-specific representation when present, then fall back to the canonical plain-text body:
+
+1. transport-native content (`slackBlocks` for Slack)
+2. plain `text`
+
+`markdown` is supplementary for markdown-aware surfaces and should not replace the canonical plain-text body on plain-text transports like iMessage.
+
+This keeps Slack, markdown-oriented exports, and plain-text sends aligned without requiring every caller to collapse everything into one presentation string upfront.

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+export type RuntimeScopeSource = "explicit" | "compatibility";
+export declare const DEFAULT_COMPATIBILITY_SCOPE_KEY = "default";
+export interface WorkspaceInstallScopeCarrier {
+    provider: string;
+    source: RuntimeScopeSource;
+    compatibilityKey?: string;
+    workspaceId?: string;
+    installId?: string;
+    channelId?: string;
+}
+export interface InstanceScopeCarrier {
+    source: RuntimeScopeSource;
+    compatibilityKey?: string;
+    instanceId?: string;
+    instanceName?: string;
+}
+export interface RuntimeScopeCarrier {
+    workspace?: WorkspaceInstallScopeCarrier;
+    instance?: InstanceScopeCarrier;
+}
+export declare function buildCompatibilityWorkspaceScope(options: {
+    provider: string;
+    workspaceId?: string | null;
+    installId?: string | null;
+    channelId?: string | null;
+    compatibilityKey?: string | null;
+}): WorkspaceInstallScopeCarrier;
+export declare function buildCompatibilityInstanceScope(options?: {
+    instanceId?: string | null;
+    instanceName?: string | null;
+    compatibilityKey?: string | null;
+}): InstanceScopeCarrier;
+export declare function buildRuntimeScopeCarrier(options: {
+    workspace?: WorkspaceInstallScopeCarrier | null;
+    instance?: InstanceScopeCarrier | null;
+}): RuntimeScopeCarrier | undefined;
+export interface InboundMessage {
+    source: string;
+    threadId: string;
+    channel: string;
+    userId: string;
+    userName?: string;
+    text: string;
+    timestamp: string;
+    isChannelMention?: boolean;
+    metadata?: Record<string, unknown>;
+    scope?: RuntimeScopeCarrier;
+}
+export interface NormalizedMessageContent {
+    text: string;
+    markdown?: string;
+    /**
+     * Compatibility/native-rendering escape hatch for Slack Block Kit payloads.
+     * This remains intentionally Slack-shaped for the current publish-readiness
+     * track while a future transport-neutral rich-content model is considered.
+     */
+    slackBlocks?: ReadonlyArray<Record<string, unknown>>;
+}
+export interface OutboundMessage {
+    threadId: string;
+    channel: string;
+    text: string;
+    content?: NormalizedMessageContent;
+    blocks?: ReadonlyArray<Record<string, unknown>>;
+    agentName?: string;
+    agentEmoji?: string;
+    agentOwnerToken?: string;
+    metadata?: Record<string, unknown>;
+    scope?: RuntimeScopeCarrier;
+}
+export interface AdapterThreadClaimEffect {
+    threadId: string;
+    channel?: string;
+}
+export interface AdapterCapabilityEffects {
+    claimThread?: AdapterThreadClaimEffect | ReadonlyArray<AdapterThreadClaimEffect>;
+}
+export interface AdapterCapabilityRequest {
+    capability: string;
+    params: Record<string, unknown>;
+}
+export interface AdapterCapabilityResult {
+    result: Record<string, unknown>;
+    effects?: AdapterCapabilityEffects;
+}
+export interface MessageAdapter {
+    name: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    onInbound(handler: (msg: InboundMessage) => void): void;
+    send(msg: OutboundMessage): Promise<void>;
+    invokeCapability?(request: AdapterCapabilityRequest): Promise<AdapterCapabilityResult>;
+}

package/dist/index.js

@@ -0,0 +1,43 @@
+export const DEFAULT_COMPATIBILITY_SCOPE_KEY = "default";
+function normalizeScopeValue(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
+export function buildCompatibilityWorkspaceScope(options) {
+    return {
+        provider: options.provider,
+        source: "compatibility",
+        compatibilityKey: normalizeScopeValue(options.compatibilityKey) ?? DEFAULT_COMPATIBILITY_SCOPE_KEY,
+        ...(normalizeScopeValue(options.workspaceId)
+            ? { workspaceId: normalizeScopeValue(options.workspaceId) }
+            : {}),
+        ...(normalizeScopeValue(options.installId)
+            ? { installId: normalizeScopeValue(options.installId) }
+            : {}),
+        ...(normalizeScopeValue(options.channelId)
+            ? { channelId: normalizeScopeValue(options.channelId) }
+            : {}),
+    };
+}
+export function buildCompatibilityInstanceScope(options = {}) {
+    return {
+        source: "compatibility",
+        compatibilityKey: normalizeScopeValue(options.compatibilityKey) ?? DEFAULT_COMPATIBILITY_SCOPE_KEY,
+        ...(normalizeScopeValue(options.instanceId)
+            ? { instanceId: normalizeScopeValue(options.instanceId) }
+            : {}),
+        ...(normalizeScopeValue(options.instanceName)
+            ? { instanceName: normalizeScopeValue(options.instanceName) }
+            : {}),
+    };
+}
+export function buildRuntimeScopeCarrier(options) {
+    const scope = {};
+    if (options.workspace) {
+        scope.workspace = options.workspace;
+    }
+    if (options.instance) {
+        scope.instance = options.instance;
+    }
+    return Object.keys(scope).length > 0 ? scope : undefined;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@pinet/transport-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Transport-neutral message contracts for pi transports",
+  "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gugu91/extensions.git",
+    "directory": "transport-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist/"
+  ],
+  "pi": {},
+  "scripts": {
+    "build": "node ../scripts/build-package.mjs",
+    "prepack": "pnpm run build",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test *.test.ts"
+  },
+  "types": "./dist/index.d.ts"
+}