@bzzsocial/ndk 0.0.0-stage → 3.0.3-bzz.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Pablo Fernandez
+
+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,105 @@
-# Temporary Holding Version
+# @nostr-dev-kit/ndk
 
-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.
+[![npm version](https://img.shields.io/npm/v/@nostr-dev-kit/ndk.svg)](https://www.npmjs.com/package/@nostr-dev-kit/ndk)
+[![Build Status](https://github.com/nostr-dev-kit/ndk/actions/workflows/deploy.yml/badge.svg)](https://github.com/nostr-dev-kit/ndk/actions)
+[![AI Guardrails Included](https://img.shields.io/badge/AI%20Guardrails-Included-brightgreen)](https://github.com/nostr-dev-kit/ndk/tree/master/ndk/src/ai-guardrails)
+
+> NDK (Nostr Development Kit) is a TypeScript/JavaScript library that simplifies building Nostr clients, relays, and related applications.
+
+## ⚠️ Important: Enable AI Guardrails
+
+**If you're new to NDK or using an AI assistant, enable AI Guardrails:**
+
+```typescript
+const ndk = new NDK({ aiGuardrails: true });
+```
+
+This prevents 90% of common mistakes (bech32 in filters, missing fields, invalid formats) with clear error messages. Disable in production.
+
+## 🤖 For AI Assistants & New Developers
+
+NDK includes **AI Guardrails** - runtime validation that catches common mistakes:
+
+- Using npub/note1 in filters (must be hex)
+- Missing required fields on events
+- Invalid tag formats
+- Performance anti-patterns
+
+**Enable with `aiGuardrails: true`** - see Quick Start below.
+
+## Features
+
+- Outbox model support
+- Relay connection pool with automatic reconnection and failover
+- Flexible subscription API with caching, batching, and auto-closing
+- Event creation, validation, and wrappers for major NIPs (e.g., NIP-01, NIP-04, NIP-07, NIP-18, NIP-49, NIP-57, NIP-60, NIP-61)
+- Signer adapters: private key, encrypted keys (NIP-49), browser extension (NIP-07), remote signing (NIP-46)
+- Pluggable cache adapters (Redis, Dexie, SQLite, etc.)
+- Data Vending Machine support (NIP-90)
+- Zap utilities (NIP-57, NIP-61)
+- Threading, event kinds, and utility functions (URL normalization, metadata tags, filters)
+- Modular design with many pluggable packages for different frameworks (Mobile, Svelte 4 and 5, React)
+
+## Installation
+
+```bash
+npm install @nostr-dev-kit/ndk
+# or
+yarn add @nostr-dev-kit/ndk
+# or
+bun add @nostr-dev-kit/ndk
+```
+
+## Quick Start
+
+```typescript
+import NDK, { NDKEvent, NDKPrivateKeySigner } from '@nostr-dev-kit/ndk';
+
+async function main() {
+  const signer = NDKPrivateKeySigner.generate();
+  const ndk = new NDK({
+    explicitRelayUrls: ['wss://relay.primal.net'],
+    signer,
+
+    // ⚠️ STRONGLY RECOMMENDED: Enable during development
+    // Catches common mistakes before they cause silent failures
+    aiGuardrails: true
+  });
+
+  // Connect to relays
+  await ndk.connect();
+
+  // Publish a simple text note
+  const event = new NDKEvent(ndk, {
+    kind: 1,
+    content: 'Hello Nostr via NDK!',
+  })
+  await event.sign();
+  event.publish();
+
+ // subscribe to all event interactions
+  ndk.subscribe(event.filter(), { closeOnEose: false }, {
+   onEvent: (replyEvent: NDKEvent) => console.log(replyEvent.author.npub, "interacted with our hello world with a kind", replyEvent.kind);
+  })
+
+  // Subscribe to incoming text notes
+  const subscription = ndk.subscribe(
+    { kinds: [1] },
+    { closeOnEose: true },
+    {
+      onEvent: (evt) => console.log('Received event:', evt),
+      onEose: () => console.log('End of stream'),
+    }
+  );
+}
+
+main().catch(console.error);
+```
+
+## Documentation
+
+Full API reference and guides are available at [https://nostr-dev-kit.github.io/ndk](https://nostr-dev-kit.github.io/ndk).
+
+## License
+
+MIT