@hatk/hatk 0.0.1-alpha.7 → 0.0.1-alpha.71

package/dist/lexicons/dev/hatk/applyWrites.json

@@ -0,0 +1,87 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.applyWrites",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Apply multiple record writes in a single atomic PDS transaction.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["writes"],
+          "properties": {
+            "writes": {
+              "type": "array",
+              "items": {
+                "type": "union",
+                "refs": ["#create", "#update", "#delete"]
+              }
+            }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "results": {
+              "type": "array",
+              "items": {
+                "type": "union",
+                "refs": ["#createResult", "#updateResult", "#deleteResult"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "create": {
+      "type": "object",
+      "required": ["collection", "value"],
+      "properties": {
+        "collection": { "type": "string" },
+        "rkey": { "type": "string" },
+        "value": { "type": "unknown" }
+      }
+    },
+    "update": {
+      "type": "object",
+      "required": ["collection", "rkey", "value"],
+      "properties": {
+        "collection": { "type": "string" },
+        "rkey": { "type": "string" },
+        "value": { "type": "unknown" }
+      }
+    },
+    "delete": {
+      "type": "object",
+      "required": ["collection", "rkey"],
+      "properties": {
+        "collection": { "type": "string" },
+        "rkey": { "type": "string" }
+      }
+    },
+    "createResult": {
+      "type": "object",
+      "required": ["uri", "cid"],
+      "properties": {
+        "uri": { "type": "string", "format": "at-uri" },
+        "cid": { "type": "string", "format": "cid" }
+      }
+    },
+    "updateResult": {
+      "type": "object",
+      "required": ["uri", "cid"],
+      "properties": {
+        "uri": { "type": "string", "format": "at-uri" },
+        "cid": { "type": "string", "format": "cid" }
+      }
+    },
+    "deleteResult": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+}

package/dist/lexicons/dev/hatk/createRecord.json

@@ -0,0 +1,40 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.createRecord",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Create a record via the user's PDS.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["collection", "repo", "record"],
+          "properties": {
+            "collection": { "type": "string" },
+            "repo": { "type": "string", "format": "did" },
+            "record": { "type": "unknown" }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "uri": { "type": "string", "format": "at-uri" },
+            "cid": { "type": "string", "format": "cid" },
+            "commit": {
+              "type": "object",
+              "properties": {
+                "cid": { "type": "string", "format": "cid" },
+                "rev": { "type": "string" }
+              }
+            },
+            "validationStatus": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/createReport.json

@@ -0,0 +1,48 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.createReport",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Report an account or record for moderation review.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["subject", "label"],
+          "properties": {
+            "subject": {
+              "type": "union",
+              "description": "The account or record being reported.",
+              "refs": ["#repoRef", "com.atproto.repo.strongRef"]
+            },
+            "label": { "type": "string", "description": "Label identifier for the report reason." },
+            "reason": { "type": "string", "maxLength": 2000, "description": "Optional free-text explanation." }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["id", "subject", "label", "reportedBy", "createdAt"],
+          "properties": {
+            "id": { "type": "integer" },
+            "subject": { "type": "unknown" },
+            "label": { "type": "string" },
+            "reason": { "type": "string" },
+            "reportedBy": { "type": "string", "format": "did" },
+            "createdAt": { "type": "string", "format": "datetime" }
+          }
+        }
+      }
+    },
+    "repoRef": {
+      "type": "object",
+      "required": ["did"],
+      "properties": {
+        "did": { "type": "string", "format": "did" }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/deleteRecord.json

@@ -0,0 +1,25 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.deleteRecord",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Delete a record via the user's PDS.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["collection", "rkey"],
+          "properties": {
+            "collection": { "type": "string" },
+            "rkey": { "type": "string" }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": { "type": "object", "properties": {} }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/describeCollections.json

@@ -0,0 +1,41 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.describeCollections",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List indexed collections and their schemas.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "collections": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["collection"],
+                "properties": {
+                  "collection": { "type": "string" },
+                  "columns": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": ["name", "originalName", "type", "required"],
+                      "properties": {
+                        "name": { "type": "string" },
+                        "originalName": { "type": "string" },
+                        "type": { "type": "string" },
+                        "required": { "type": "boolean" }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/describeFeeds.json

@@ -0,0 +1,29 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.describeFeeds",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List available feeds.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "feeds": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["name", "label"],
+                "properties": {
+                  "name": { "type": "string" },
+                  "label": { "type": "string" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/describeLabels.json

@@ -0,0 +1,45 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.describeLabels",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List available label definitions.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "definitions": {
+              "type": "array",
+              "items": { "type": "ref", "ref": "#labelDefinition" }
+            }
+          }
+        }
+      }
+    },
+    "labelDefinition": {
+      "type": "object",
+      "required": ["identifier", "severity", "blurs", "defaultSetting"],
+      "properties": {
+        "identifier": { "type": "string" },
+        "severity": { "type": "string" },
+        "blurs": { "type": "string" },
+        "defaultSetting": { "type": "string" },
+        "locales": {
+          "type": "array",
+          "items": { "type": "ref", "ref": "#labelLocale" }
+        }
+      }
+    },
+    "labelLocale": {
+      "type": "object",
+      "required": ["lang", "name", "description"],
+      "properties": {
+        "lang": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/getFeed.json

@@ -0,0 +1,30 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.getFeed",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Retrieve a named feed of items.",
+      "parameters": {
+        "type": "params",
+        "required": ["feed"],
+        "properties": {
+          "feed": { "type": "string", "description": "Feed name" },
+          "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 },
+          "cursor": { "type": "string" }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["items"],
+          "properties": {
+            "items": { "type": "array", "items": { "type": "unknown" } },
+            "cursor": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/getPreferences.json

@@ -0,0 +1,19 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.getPreferences",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Get all preferences for the authenticated user.",
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "preferences": { "type": "unknown" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/getRecord.json

@@ -0,0 +1,26 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.getRecord",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Fetch a single record by AT URI.",
+      "parameters": {
+        "type": "params",
+        "required": ["uri"],
+        "properties": {
+          "uri": { "type": "string", "format": "at-uri" }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "record": { "type": "unknown" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/getRecords.json

@@ -0,0 +1,32 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.getRecords",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "List records from a collection with optional filters.",
+      "parameters": {
+        "type": "params",
+        "required": ["collection"],
+        "properties": {
+          "collection": { "type": "string" },
+          "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+          "cursor": { "type": "string" },
+          "sort": { "type": "string" },
+          "order": { "type": "string" }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["items"],
+          "properties": {
+            "items": { "type": "array", "items": { "type": "unknown" } },
+            "cursor": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/putPreference.json

@@ -0,0 +1,28 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.putPreference",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Set a single preference by key.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["key", "value"],
+          "properties": {
+            "key": { "type": "string" },
+            "value": { "type": "unknown" }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {}
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/putRecord.json

@@ -0,0 +1,41 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.putRecord",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Create or update a record via the user's PDS.",
+      "input": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["collection", "rkey", "record"],
+          "properties": {
+            "collection": { "type": "string" },
+            "rkey": { "type": "string" },
+            "record": { "type": "unknown" },
+            "repo": { "type": "string", "format": "did" }
+          }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "properties": {
+            "uri": { "type": "string", "format": "at-uri" },
+            "cid": { "type": "string", "format": "cid" },
+            "commit": {
+              "type": "object",
+              "properties": {
+                "cid": { "type": "string", "format": "cid" },
+                "rev": { "type": "string" }
+              }
+            },
+            "validationStatus": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/searchRecords.json

@@ -0,0 +1,32 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.searchRecords",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Full-text search across a collection.",
+      "parameters": {
+        "type": "params",
+        "required": ["collection", "q"],
+        "properties": {
+          "collection": { "type": "string" },
+          "q": { "type": "string", "description": "Search query" },
+          "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+          "cursor": { "type": "string" },
+          "fuzzy": { "type": "boolean", "default": true }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["items"],
+          "properties": {
+            "items": { "type": "array", "items": { "type": "unknown" } },
+            "cursor": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/lexicons/dev/hatk/uploadBlob.json

@@ -0,0 +1,23 @@
+{
+  "lexicon": 1,
+  "id": "dev.hatk.uploadBlob",
+  "defs": {
+    "main": {
+      "type": "procedure",
+      "description": "Upload a blob via the user's PDS.",
+      "input": {
+        "encoding": "*/*"
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["blob"],
+          "properties": {
+            "blob": { "type": "blob" }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/logger.d.ts

@@ -1,4 +1,33 @@
+/**
+ * Unstructured debug log — use sparingly for human-readable dev output.
+ * Prefer {@link emit} for anything that should be queryable in production.
+ * Disabled when `DEBUG=0`.
+ */
 export declare function log(...args: unknown[]): void;
+/**
+ * Emit a structured wide event as a single JSON line to stdout.
+ *
+ * Each call produces one canonical log line with a timestamp, module, operation,
+ * and arbitrary key-value fields — designed for columnar search and aggregation,
+ * not string grep. Pack as much context as possible into `fields` (request IDs,
+ * durations, status codes, user DIDs, counts) so a single event tells the full
+ * story. See https://loggingsucks.com for the philosophy behind this approach.
+ *
+ * Disabled when `DEBUG=0`.
+ *
+ * @param module - Subsystem emitting the event (e.g. "server", "indexer", "backfill")
+ * @param op - Operation name (e.g. "request", "commit", "memory")
+ * @param fields - High-cardinality key-value context — include everything relevant
+ */
 export declare function emit(module: string, op: string, fields: Record<string, unknown>): void;
+/**
+ * Start a millisecond timer. Call the returned function to get elapsed ms.
+ * Use with {@link emit} to add `duration_ms` to wide events.
+ *
+ * @example
+ * const elapsed = timer()
+ * await doWork()
+ * emit('server', 'request', { path, status_code, duration_ms: elapsed() })
+ */
 export declare function timer(): () => number;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG5C;AAED,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED,wBAAgB,KAAK,IAAI,MAAM,MAAM,CAGpC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAWtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,IAAI,MAAM,MAAM,CAGpC"}

package/dist/logger.js

@@ -1,8 +1,28 @@
+/**
+ * Unstructured debug log — use sparingly for human-readable dev output.
+ * Prefer {@link emit} for anything that should be queryable in production.
+ * Disabled when `DEBUG=0`.
+ */
 export function log(...args) {
     if (process.env.DEBUG === '0')
         return;
     console.log(...args);
 }
+/**
+ * Emit a structured wide event as a single JSON line to stdout.
+ *
+ * Each call produces one canonical log line with a timestamp, module, operation,
+ * and arbitrary key-value fields — designed for columnar search and aggregation,
+ * not string grep. Pack as much context as possible into `fields` (request IDs,
+ * durations, status codes, user DIDs, counts) so a single event tells the full
+ * story. See https://loggingsucks.com for the philosophy behind this approach.
+ *
+ * Disabled when `DEBUG=0`.
+ *
+ * @param module - Subsystem emitting the event (e.g. "server", "indexer", "backfill")
+ * @param op - Operation name (e.g. "request", "commit", "memory")
+ * @param fields - High-cardinality key-value context — include everything relevant
+ */
 export function emit(module, op, fields) {
     if (process.env.DEBUG === '0')
         return;
@@ -17,6 +37,15 @@ export function emit(module, op, fields) {
     }
     process.stdout.write(JSON.stringify(entry) + '\n');
 }
+/**
+ * Start a millisecond timer. Call the returned function to get elapsed ms.
+ * Use with {@link emit} to add `duration_ms` to wide events.
+ *
+ * @example
+ * const elapsed = timer()
+ * await doWork()
+ * emit('server', 'request', { path, status_code, duration_ms: elapsed() })
+ */
 export function timer() {
     const start = performance.now();
     return () => Math.round(performance.now() - start);