use thirdparty/ folder, natspec comments, psqlUrl for optional replic…

…ator

src/providers/class.ts

@@ -1,22 +1,40 @@
 export class Provider {
-    name: string;
-    constructor(name: string) {
-      this.name = name;
-    }
+  name: string;
+  /**
+   * Generic base Provider Class, don't use directly!
+   * @param name the custom name of the provider. useful for debugging output
+   */
+  constructor(name: string) {
+    this.name = name;
   }
+}
 
 export class HubProvider extends Provider {
-    hubUrl: string;
-    constructor(name: string, hubUrl: string) {
-      super(name);
-      this.hubUrl = hubUrl;
-    }
+  hubUrl: string;
+  psqlUrl: string | undefined;
+  /**
+   * HubProvider for getting Data with Farcaster Hubs and optional PostgreSQL Replicator
+   * @param name the custom name of the provider. useful for debugging output
+   * @param hubUrl the Farcaster Hub URL to use
+   * @param psqlUrl optional: the PostgreSQL Replicator URL to use. Defaults to undefined
+   */
+  constructor(name: string, hubUrl: string, psqlUrl?: string) {
+    super(name);
+
+    this.hubUrl = hubUrl;
+    this.psqlUrl = psqlUrl;
   }
+}
 
 export class ThirdParty extends Provider {
   apiKey: string;
   endPoint: string;
 
+  /**
+   * ThirdParty Provider for getting Data with any ThirdParty API provider that doesn't just offer a Hub/Replicator Endpoint
+   * @param apiKey Provider API Key to use. Please do not hardcode this! Use .env or other
+   * @param endPoint the Provider API endpoint to use
+   */
   constructor(name: string, apiKey: string, endPoint: string) {
       super(name);
       this.apiKey = apiKey;

src/providers/index.ts

@@ -1,3 +1,3 @@
 export * from "./class";
 export * from "./public";
-export * from "./thirdparty";
+export * from "./thirdpartyProvider";

src/providers/public.ts

@@ -1,21 +1,31 @@
 import { HubProvider } from './class';
 
-
-
+// Example usage for a predefined provider
+// const provider = new PublicProvider();
+// to use the public Pinata Farcaster Hub
+// const provider = new PublicProvider("pinata");
+// to use with PostgreSQL Replicator at https://replicator.yourdomain.com
+// const provider = new PublicProvider("pinata", "https://replicator.yourdomain.com");
 
 export class PublicProvider extends HubProvider {
-  constructor(name: string = 'farcaster', providerType: string = 'farcaster') {
+    /**
+     * Default Provider using only free, public Offerings anyone can use!
+     * @param providerType decide which public Hub to use. Defaults to Warpcast offering
+     * @param psqlUrl optional: the PostgreSQL Replicator URL to use. Defaults to undefined
+     */
+  constructor(providerType: string = 'farcaster', psqlUrl?: string) {
     let hubUrl: string;
+    let name: string;
+
     if (providerType === 'pinata') {
       hubUrl = 'hub.pinata.cloud/v1/';
+      name = 'publicPinataHub';
     } else {
       hubUrl = 'nemes.farcaster.xyz:2283';
+      name = 'publicFarcasterHub';
     }
-    super(name, hubUrl);
+    //no psqlUrl since there is no public PostgreSQL Replicator instance
+    super(name, hubUrl, psqlUrl);
   }
 }
 
-// Example usage for a predefined provider
-// const provider = new PublicProvider("farcaster");
-// const provider = new PublicProvider("pinata");
-// const provider = new PublicProvider();

src/providers/thirdparty/neynarProvider.ts

@@ -0,0 +1,28 @@
+import { NeynarAPIClient } from "@neynar/nodejs-sdk";
+
+import { ThirdParty } from "../class";
+
+/*
+ * Example usage for neynar provider
+ * const neynarApiKey = process.env.NEYNAR_API_KEY || "your_neynar_api_key"; 
+ * const neynarProvider = new NeynarProvider(neynarApiKey);
+ */
+
+export class NeynarProvider extends ThirdParty {
+    /**
+     * NeynarProvider for getting Data with neynar.com Farcaster APIs
+     * @param apiKey Neynar API Key to use. Please do not hardcode this! Use .env or other
+     * @param endPoint optional Neynar API endpoint, defaults to public Neynar V2. Custom endpoint is required to be Neynar API V2 compliant! 
+     */
+    constructor(apiKey: string, endPoint?: string) {
+        if (endPoint) {
+            super("neynar", apiKey, endPoint);
+        } else {
+            super("neynar", apiKey, "https://api.neynar.com/v2/farcaster");
+        }
+    }
+
+    client() {
+        return new NeynarAPIClient(this.apiKey);
+    }
+}

src/providers/thirdpartyProvider.ts

@@ -0,0 +1,35 @@
+import { ThirdParty } from "./class";
+
+/**
+ * 
+ * NOTE: This implementation is a sample and will lead to unimplemented Errors with FarcasterKit Providers!
+ *       The only exception to this is functions that require only Hubs as there we fall back to the public Provider.
+ *       For Farcaster API providers who wish to offer the API to FarcasterKit developers please open a PullRequest/Issue
+ *       https://github.com/dtechvision/farcasterkit/
+ * 
+ */
+
+export class ThirdPartyProvider extends ThirdParty {
+    /**
+     * Custom Third Party Provider for getting Data with custom APIs
+     * @param providerType name the type of provider you are creating
+     * @param apiKey the API Key to use with your API Endpoint if required
+     * @param endPoint your custom API Endpoint that should be used
+     */
+    constructor(providerType: string, apiKey: string, endPoint: string) {
+        if (!endPoint) {
+            throw new Error("Endpoint must be provided for custom provider type");
+        } 
+        if(!providerType) {
+            throw new Error('Provider type must be provided for custom provider type');
+        }
+
+        super(providerType, apiKey, endPoint);
+    }
+}
+
+/****************************************
+ * all registered third party providers *
+ ****************************************/
+
+export * from './thirdparty/neynarProvider';