@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/sync/index.js

@@ -0,0 +1,14 @@
+export { classifySyncFailure, inferPayloadKind, } from "./issues.js";
+export { createSyncManager, } from "./engine/sync-manager.js";
+// The single-data-point download path, exported so an integration test can
+// drive the REAL decrypt-and-index worker end to end rather than restate it.
+export { downloadOne } from "./workers/download.js";
+export { createPdppImporter, isPermanentRejection, normalizeDigest, PDPP_METADATA_KEY, SUPPORTED_PDPP_METADATA_VERSION, } from "./pdpp-import.js";
+export { BLOB_DELETE_BATCH_SIZE, deleteScope, planBlobDeletions, retryPendingBlobDeletions, } from "./workers/delete.js";
+export { createGatewayDataPointFeed, feedFromGatewayClient, } from "./data-point-feed.js";
+export { createGatewayDeleteDataPort, } from "./delete-data-port.js";
+export { createMemoryPendingBlobDeletionStore, createPendingBlobDeletionStore, normalizePendingBlobDeletions, } from "./pending-blob-deletions.js";
+export { computeDataPointId } from "./data-point-id.js";
+export { createScopeDeletionTracker, deletionTimestamp, isEntryCoveredByTombstone, tombstoneVersion, DEFAULT_SCOPE_DELETION_GATEWAY_RETRY_MS, DEFAULT_SCOPE_DELETION_MAX_STALENESS_MS, } from "./scope-deletions.js";
+export { TOMBSTONE_DATA_HASH, TOMBSTONE_METADATA_HASH, isTombstoneRecord, } from "./tombstone.js";
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,GAGlB,MAAM,0BAA0B,CAAC;AAKlC,2EAA2E;AAC3E,6EAA6E;AAC7E,OAAO,EAAE,WAAW,EAAuB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,+BAA+B,GAShC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,WAAW,EACX,iBAAiB,EACjB,yBAAyB,GAM1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,GAEtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,2BAA2B,GAE5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oCAAoC,EACpC,8BAA8B,EAC9B,6BAA6B,GAE9B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,EACjB,yBAAyB,EACzB,gBAAgB,EAChB,uCAAuC,EACvC,uCAAuC,GAOxC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC"}

package/dist/sync/issues.d.ts

@@ -0,0 +1,55 @@
+export type SyncFailureStage = "download" | "openpgp_parse" | "decrypt" | "json_parse" | "envelope_validate" | "block_build" | "unknown";
+export type SyncPayloadKind = "openpgp" | "json" | "html" | "empty" | "binary" | "unknown";
+export type SyncFailureDisposition = "deterministic" | "transient";
+export interface SyncFileIssue {
+    fileId: string;
+    schemaId?: string;
+    scope?: string;
+    stage: SyncFailureStage;
+    errorClass: string;
+    message: string;
+    payloadKind?: SyncPayloadKind;
+    encryptedSizeBytes?: number;
+    syncRunId: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    disposition: SyncFailureDisposition;
+    retryable: boolean;
+}
+export interface SyncDownloadFailureTelemetryEvent {
+    event: "sync.download.failure";
+    syncRunId: string;
+    fileId: string;
+    schemaId?: string;
+    scope?: string;
+    stage: SyncFailureStage;
+    payloadKind?: SyncPayloadKind;
+    encryptedSizeBytes?: number;
+    errorClass: string;
+    disposition: SyncFailureDisposition;
+    retryable: boolean;
+    appVersion?: string;
+    personalServerVersion?: string;
+    storageBackend?: string;
+}
+export interface ClassifySyncFailureInput {
+    error: unknown;
+    fileId: string;
+    syncRunId: string;
+    stage?: SyncFailureStage;
+    schemaId?: string;
+    scope?: string;
+    payloadKind?: SyncPayloadKind;
+    encryptedSizeBytes?: number;
+    now?: Date;
+    appVersion?: string;
+    personalServerVersion?: string;
+    storageBackend?: string;
+}
+export interface ClassifiedSyncFailure {
+    issue: SyncFileIssue;
+    telemetry: SyncDownloadFailureTelemetryEvent;
+}
+export declare function classifySyncFailure(input: ClassifySyncFailureInput): ClassifiedSyncFailure;
+export declare function inferPayloadKind(bytes: Uint8Array | string): SyncPayloadKind;
+//# sourceMappingURL=issues.d.ts.map

package/dist/sync/issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../src/sync/issues.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,eAAe,GACf,SAAS,GACT,YAAY,GACZ,mBAAmB,GACnB,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,MAAM,eAAe,GACzB,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,gBAAgB,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,sBAAsB,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iCAAiC;IAChD,KAAK,EAAE,uBAAuB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,sBAAsB,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,iCAAiC,CAAC;CAC9C;AAiBD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,GAC9B,qBAAqB,CA0CvB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,eAAe,CAgB5E"}

package/dist/sync/issues.js

@@ -0,0 +1,168 @@
+const DETERMINISTIC_STAGES = new Set([
+    "openpgp_parse",
+    "decrypt",
+    "json_parse",
+    "envelope_validate",
+    "block_build",
+]);
+// Only statuses that PROVE the blob cannot appear by retrying are
+// deterministic. Everything else — 5xx, Cloudflare 52x, 401/403 auth blips
+// (downloads are Web3Signed off the local clock), 429 — is treated as
+// transient and bounded by the retry memory's attempt cap instead of being
+// permanently quarantined on first sight.
+const DETERMINISTIC_DOWNLOAD_STATUSES = new Set([404, 410]);
+export function classifySyncFailure(input) {
+    const stage = input.stage ?? inferStage(input.error);
+    const disposition = classifyDisposition(input.error, stage);
+    const retryable = disposition === "transient";
+    const timestamp = (input.now ?? new Date()).toISOString();
+    const errorClass = getErrorClass(input.error);
+    const message = getSafeIssueMessage(stage, disposition);
+    const issue = {
+        fileId: input.fileId,
+        schemaId: input.schemaId,
+        scope: input.scope,
+        stage,
+        errorClass,
+        message,
+        payloadKind: input.payloadKind,
+        encryptedSizeBytes: input.encryptedSizeBytes,
+        syncRunId: input.syncRunId,
+        firstSeenAt: timestamp,
+        lastSeenAt: timestamp,
+        disposition,
+        retryable,
+    };
+    const telemetry = {
+        event: "sync.download.failure",
+        syncRunId: input.syncRunId,
+        fileId: input.fileId,
+        schemaId: input.schemaId,
+        scope: input.scope,
+        stage,
+        payloadKind: input.payloadKind,
+        encryptedSizeBytes: input.encryptedSizeBytes,
+        errorClass,
+        disposition,
+        retryable,
+        appVersion: input.appVersion,
+        personalServerVersion: input.personalServerVersion,
+        storageBackend: input.storageBackend,
+    };
+    return { issue, telemetry };
+}
+export function inferPayloadKind(bytes) {
+    const text = typeof bytes === "string"
+        ? bytes
+        : new TextDecoder().decode(bytes.slice(0, 256));
+    const trimmed = text.trimStart();
+    if (trimmed.length === 0)
+        return "empty";
+    if (trimmed.startsWith("-----BEGIN PGP MESSAGE-----"))
+        return "openpgp";
+    if (trimmed.startsWith("{") || trimmed.startsWith("["))
+        return "json";
+    if (/^<!doctype html\b/i.test(trimmed) || /^<html[\s>]/i.test(trimmed)) {
+        return "html";
+    }
+    if (containsBinaryByte(bytes))
+        return "binary";
+    return "unknown";
+}
+function classifyDisposition(error, stage) {
+    if (stage === "download") {
+        const status = getNumericProperty(error, "status") ??
+            getNumericProperty(error, "statusCode") ??
+            getDownloadStatusFromMessage(error);
+        if (status !== undefined) {
+            return DETERMINISTIC_DOWNLOAD_STATUSES.has(status)
+                ? "deterministic"
+                : "transient";
+        }
+        return "transient";
+    }
+    if (DETERMINISTIC_STAGES.has(stage)) {
+        return "deterministic";
+    }
+    return "transient";
+}
+function inferStage(error) {
+    if (error instanceof SyntaxError)
+        return "json_parse";
+    const name = getStringProperty(error, "name").toLowerCase();
+    const message = getRawMessage(error).toLowerCase();
+    if (name === "zoderror" || message.includes("zod"))
+        return "envelope_validate";
+    if (message.includes("decrypt") || message.includes("session key"))
+        return "decrypt";
+    if (message.includes("openpgp") || message.includes("pgp message")) {
+        return "openpgp_parse";
+    }
+    return "unknown";
+}
+function getErrorClass(error) {
+    const name = getStringProperty(error, "name");
+    if (name.length > 0)
+        return name;
+    if (error instanceof Error && error.constructor.name.length > 0) {
+        return error.constructor.name;
+    }
+    return typeof error;
+}
+function getRawMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    const message = getStringProperty(error, "message");
+    return message.length > 0 ? message : "Unknown sync failure";
+}
+function getStringProperty(value, key) {
+    if (typeof value !== "object" || value === null || !(key in value))
+        return "";
+    const property = value[key];
+    return typeof property === "string" ? property : "";
+}
+// The SDK's StorageError carries the HTTP status only in its message —
+// "vana-storage download failed: 404 Not Found" — with no numeric property.
+// Without this fallback a 404'd blob classifies transient and is retried
+// every sync cycle forever. The anchored "download failed: " prefix mirrors
+// the provider's stable message shape and avoids misreading digits in
+// network-error causes (IPs, ports), which stay transient.
+function getDownloadStatusFromMessage(error) {
+    const match = /download failed: ([1-5]\d{2})\b/.exec(getRawMessage(error));
+    return match ? Number(match[1]) : undefined;
+}
+function getNumericProperty(value, key) {
+    if (typeof value !== "object" || value === null || !(key in value)) {
+        return undefined;
+    }
+    const property = value[key];
+    return typeof property === "number" ? property : undefined;
+}
+function containsBinaryByte(bytes) {
+    if (typeof bytes === "string")
+        return false;
+    return bytes.some((byte) => byte === 0 || (byte < 0x09 && byte !== 0x07));
+}
+function getSafeIssueMessage(stage, disposition) {
+    switch (stage) {
+        case "download":
+            return disposition === "transient"
+                ? "Download failed with a retryable storage or network error"
+                : "Download failed with a non-retryable storage response";
+        case "openpgp_parse":
+            return "Encrypted payload could not be parsed as an OpenPGP message";
+        case "decrypt":
+            return "Encrypted payload could not be decrypted";
+        case "json_parse":
+            return "Decrypted payload could not be parsed as JSON";
+        case "envelope_validate":
+            return "Decrypted JSON did not match the expected envelope shape";
+        case "block_build":
+            return "Envelope was stored, but bounded block build failed";
+        case "unknown":
+            return "Sync file failed at an unknown stage";
+    }
+}
+//# sourceMappingURL=issues.js.map

package/dist/sync/issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.js","sourceRoot":"","sources":["../../src/sync/issues.ts"],"names":[],"mappings":"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"}

package/dist/sync/pdpp-import.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Import qualifying synced DataPipe envelopes into the PDPP record store.
+ *
+ * The production path already existed end to end: Unity's OwnerDataClient
+ * writes an encrypted `DataFileEnvelope` and registers it with the Gateway,
+ * and `sync/workers/download.ts` downloads, decrypts and indexes it. What was
+ * missing was the last hop — that decrypted envelope reaching the PDPP record
+ * store, so a grant-bound client can read it. This module is that hop, and
+ * nothing else: it does not fetch, does not decrypt, and does not open a
+ * second ingestion surface. There is no web HTTP ingest here by design; the
+ * encrypted owner-data transport stays the only way data arrives.
+ *
+ * Why the metadata lives in `data.$pdpp`
+ * -------------------------------------
+ * The SDK's `DataFileEnvelopeSchema` accepts only `$schema`, `version`,
+ * `scope`, `schemaId`, `collectedAt` and `data`, and STRIPS unknown top-level
+ * keys. A `$pdpp` sibling of `scope` would therefore be silently deleted in
+ * transit — not rejected, deleted — so the producer nests it inside `data`,
+ * the one field whose interior the transport preserves verbatim. That is a
+ * transport constraint, not a preference.
+ *
+ * The consequence this module owns: `$pdpp` is import metadata that arrived
+ * inside the payload, so it must be removed before the record is stored.
+ * Otherwise every PDPP read would serve back a `$pdpp` blob that is not part
+ * of the source's declared schema, and a field projection computed from the
+ * declaration would not cover it.
+ *
+ * What is verified before anything is written
+ * -------------------------------------------
+ * Every check below is a fail-closed rejection, because the alternative is
+ * importing a record whose identity or authority we could not confirm:
+ *
+ *   1. `$pdpp.version === 1`. An unknown metadata version is refused rather
+ *      than interpreted under this version's assumptions.
+ *   2. The declaration digest is recomputed over the EXACT retained
+ *      declaration document this deployment booted with, and must equal the
+ *      digest the producer claims. This is the check that makes the rest
+ *      meaningful: without it the producer would be asserting its own
+ *      authority over the stream shape it is being validated against.
+ *   3. `scope`, `stream.name` and `primaryKey` must agree with that same
+ *      declaration, and `record.key` must agree with the payload's actual
+ *      primary-key values.
+ *
+ * Only then is `$pdpp` stripped and the record handed to the store.
+ *
+ * Instance derivation is PS-owned
+ * -------------------------------
+ * The producer supplies no instance id and must not: an instance handle is a
+ * statement about this deployment's connection inventory, which the producer
+ * cannot observe. The importer derives it through the same function the
+ * authorization and resource servers use, so an imported record is readable
+ * under a grant issued for the same source. An id that cannot be derived is a
+ * rejection, never an invention.
+ */
+import type { PdppRecordStore, StreamSemantics } from "../storage/pdpp-records/index.js";
+import type { Logger } from "../logger/index.js";
+/** The reserved key carrying PDPP import metadata inside `data`. */
+export declare const PDPP_METADATA_KEY = "$pdpp";
+/** The only `$pdpp.version` this importer understands. */
+export declare const SUPPORTED_PDPP_METADATA_VERSION = 1;
+/**
+ * The stream shape the importer validates against, projected from the
+ * deployment's retained declaration. Deliberately not the full declaration
+ * model: the importer only needs to answer "does this envelope match the
+ * document we retained?".
+ */
+export interface ImportStreamShape {
+    name: string;
+    primaryKey: string[];
+    semantics: StreamSemantics;
+}
+/**
+ * One retained declaration, as this deployment booted with it.
+ *
+ * The digest must be taken over the exact retained bytes, not over a
+ * re-serialization of a parsed snapshot. The distinction is the whole point
+ * of the check: the authorization store persists a parsed `snapshot_json`,
+ * and re-digesting that would produce a different value than the digest
+ * recorded at retrieval (key order, whitespace, and fields the parser does
+ * not carry). Digesting anything other than the retrieved bytes would be a
+ * check that passes against itself while proving nothing about what the
+ * producer actually read.
+ */
+export interface RetainedDeclaration {
+    sourceId: string;
+    version: string;
+    /**
+     * SHA-256 over the exact retained document, as bare lowercase hex.
+     *
+     * Passed in already computed rather than hashed here on purpose. This
+     * module is bundled into the browser lite runtime, where `node:crypto` does
+     * not exist; hashing here would break that build. The server computes it
+     * once at boot from the document it read — which is also the only place the
+     * original bytes exist — so doing it there costs nothing and keeps this
+     * module runtime-agnostic.
+     */
+    documentDigest: string;
+    streams: ImportStreamShape[];
+}
+export type PdppImportRejectionCode = "no_metadata" | "malformed_metadata" | "unsupported_metadata_version" | "unknown_source" | "digest_mismatch" | "declaration_version_mismatch" | "scope_mismatch" | "unknown_stream" | "primary_key_mismatch" | "semantics_mismatch" | "record_key_mismatch" | "no_instance" | "store_rejected";
+export interface PdppImportRejection {
+    code: PdppImportRejectionCode;
+    message: string;
+}
+/**
+ * Whether a rejection is a settled verdict about the envelope itself.
+ *
+ * Callers use this to decide whether re-offering the same envelope later
+ * could ever change the answer. Fail-closed by construction: an unrecognized
+ * code is treated as transient, so a new failure mode is retried (visibly,
+ * with a logged outcome) rather than silently abandoned.
+ */
+export declare function isPermanentRejection(rejection: PdppImportRejection): boolean;
+export type PdppImportOutcome = 
+/** Not a PDPP-bearing envelope. Legacy-only, and not an error. */
+{
+    status: "skipped";
+}
+/** Imported a new version. */
+ | {
+    status: "imported";
+    instance: string;
+    stream: string;
+    recordKey: string;
+}
+/**
+ * Verified and already present unchanged. Deliberately distinct from
+ * "imported": re-writing it would allocate a new version and publish a
+ * spurious `changes_since` entry for a record that did not change.
+ */
+ | {
+    status: "unchanged";
+    instance: string;
+    stream: string;
+    recordKey: string;
+} | {
+    status: "rejected";
+    rejection: PdppImportRejection;
+};
+/** The envelope fields this importer reads. */
+export interface ImportableEnvelope {
+    scope: string;
+    collectedAt: string;
+    data: unknown;
+}
+export interface PdppImporterDeps {
+    store: PdppRecordStore;
+    /** The exact declarations this deployment retained at boot. */
+    declarations: RetainedDeclaration[];
+    /**
+     * PS-owned instance derivation, wired to the same inventory the AS and RS
+     * use so an imported record is readable under a grant for that source.
+     */
+    instanceFor: (sourceId: string) => string | undefined;
+    logger: Logger;
+}
+export interface PdppImporter {
+    /** Import one decrypted envelope. Never throws; failures are outcomes. */
+    importEnvelope(envelope: ImportableEnvelope): PdppImportOutcome;
+    /**
+     * Whether re-offering this already-indexed (scope, collectedAt) could still
+     * change anything.
+     *
+     * The retry path uses this to decide whether reading the envelope back off
+     * disk is worth doing at all. It answers false once an offer for that exact
+     * version has settled — imported, verified-unchanged, permanently rejected,
+     * or found to carry no `$pdpp` — because none of those can be changed by
+     * looking again. It answers true for a version never offered, and for one
+     * whose last attempt failed transiently.
+     *
+     * Deliberately in-memory and process-scoped. The answers it caches are all
+     * re-derivable: after a restart the first cycle re-reads each entry once and
+     * re-settles it. Persisting them would add schema and a migration to avoid
+     * a single bounded read per entry per boot, and would risk a stale "settled"
+     * row outliving the condition that produced it — the exact class of bug this
+     * whole retry path exists to fix.
+     */
+    needsRetry(scope: string, collectedAt: string): boolean;
+}
+/**
+ * Normalize a claimed digest to bare lowercase hex.
+ *
+ * The producer contract writes `sha256:<hex>`; this repo's
+ * `computeDeclarationDigest` returns bare hex with no prefix. Accepting both
+ * spellings of the same SHA-256 value keeps the two sides interoperable
+ * without either silently coercing the other. Any OTHER algorithm prefix
+ * returns null and fails the import: treating `md5:...` as if it were the
+ * SHA-256 we computed would turn the digest check into decoration.
+ */
+export declare function normalizeDigest(claimed: string): string | null;
+export declare function createPdppImporter(deps: PdppImporterDeps): PdppImporter;
+//# sourceMappingURL=pdpp-import.d.ts.map

package/dist/sync/pdpp-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdpp-import.d.ts","sourceRoot":"","sources":["../../src/sync/pdpp-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,0DAA0D;AAC1D,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,eAAe,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,MAAM,uBAAuB,GAC/B,aAAa,GACb,oBAAoB,GACpB,8BAA8B,GAC9B,gBAAgB,GAChB,iBAAiB,GACjB,8BAA8B,GAC9B,gBAAgB,GAChB,gBAAgB,GAChB,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,GACb,gBAAgB,CAAC;AAErB,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAE5E;AAED,MAAM,MAAM,iBAAiB;AAC3B,kEAAkE;AAChE;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,8BAA8B;GAC5B;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC7E;;;;GAIG;GACD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB,+DAA+D;IAC/D,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC;;;OAGG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,iBAAiB,CAAC;IAChE;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;CACzD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO9D;AAgJD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA+OvE"}