improve package for jsr

Author: shyim

packages/app-server-sdk/README.md

@@ -1,6 +1,47 @@
-# shopware-app-server
+# App Server
 
-This package provides the indepenend runtime for the Shopware App Server. It can be used to run the app server in any JS environment.
+This package can be used to create a Shopware App Backend. It's build independent of any JavaScript framework. It relies on Fetch-standardized Request and Response objects.
 
-For Cloudflare install the `@friendsofshopware/app-server-cloudflare` package.
-For Express install the `@friendsofshopware/app-server-express` package.
+## Example with Bun
+
+```js
+import { AppServer, InMemoryShopRepository } from '@friendsofshopware/app-server'
+
+const app = new AppServer({
+    appName: 'MyApp',
+    appSecret: 'my-secret',
+    authorizeCallbackUrl: 'http://localhost:3000/authorize/callback',
+}, new InMemoryShopRepository());
+
+const server = Bun.serve({
+    port: 3000,
+    async fetch(request) {
+        const { pathname } = new URL(request.url);
+        if (pathname === '/authorize') {
+            return app.registration.authorize(request);
+        } else if (pathname === '/authorize/callback') {
+            return app.registration.authorizeCallback(request);
+        } else if (pathname === '/app/product') {
+            const context = await app.contextResolver.fromSource(request);
+
+            // do something with payload, and http client
+            const resp = new Response(JSON.stringify({
+                actionType: "notification",
+                payload: {
+                    status: "success",
+                    message: "Product created",
+                }
+            }));
+
+            // sign the response, with the shop secret
+            await app.signer.signResponse(resp, context.shop.getShopSecret());
+
+            return resp;
+        }
+
+        return new Response('Not found', { status: 404 });
+    },
+});
+
+console.log(`Listening on localhost:${server.port}`);
+```

packages/app-server-sdk/app.ts

@@ -3,13 +3,16 @@ import { WebCryptoHmacSigner } from "./signer.ts";
 import { ShopRepositoryInterface } from "./repository.ts";
 import { ContextResolver } from "./context-resolver.ts";
 
+/**
+* AppServer is the main class, this is where you start your app
+*/
 export class AppServer {
   public registration: Registration;
   public contextResolver: ContextResolver;
   public signer: WebCryptoHmacSigner;
 
   constructor(
-    public cfg: AppConfigurationInterface,
+    public cfg: Configuration,
     public repository: ShopRepositoryInterface
   ) {
     this.registration = new Registration(this);
@@ -18,7 +21,7 @@ export class AppServer {
   }
 }
 
-export interface AppConfigurationInterface {
+interface Configuration {
   /**
    * Your app name
    */

packages/app-server-sdk/context-resolver.ts

@@ -2,9 +2,16 @@ import { AppServer } from "./app.ts";
 import { HttpClient } from "./http-client.ts";
 import { ShopInterface } from "./repository.ts";
 
+/**
+* ContextResolver is a helper class to create a Context object from a request.
+* The context contains the shop, the payload and an instance of the HttpClient
+*/
 export class ContextResolver {
   constructor(private app: AppServer) {}
 
+  /**
+  * Create a context from a request bodty
+  */
   public async fromSource(req: Request): Promise<Context> {
     const webHookContent = await req.text();
     const webHookBody = JSON.parse(webHookContent);
@@ -26,6 +33,10 @@ export class ContextResolver {
     return new Context(shop, webHookBody, new HttpClient(shop));
   }
 
+  /**
+  * Create a context from a request query parameters
+  * This is usually a module request from the shopware admin
+  */
   public async fromModule(req: Request): Promise<Context> {
     const url = new URL(req.url);
 
@@ -50,6 +61,9 @@ export class ContextResolver {
   }
 }
 
+/**
+* Context is the parsed data from the request
+*/
 export class Context {
   constructor(
     public shop: ShopInterface,

packages/app-server-sdk/http-client.ts

@@ -1,5 +1,8 @@
 import { ShopInterface } from "./repository.ts";
 
+/**
+* HttpClient is a simple wrapper around the fetch API, pre-configured with the shop's URL and access token
+*/
 export class HttpClient {
   private storage: { expiresIn: Date | null; token: string | null };
 
@@ -10,10 +13,16 @@ export class HttpClient {
     };
   }
 
+  /**
+  * Permform a GET request
+  */
   async get(url: string, headers: object = {}): Promise<HttpClientResponse> {
     return await this.request("GET", url, null, headers);
   }
 
+  /**
+  * Permform a POST request
+  */
   async post(
     url: string,
     json: object = {},
@@ -25,6 +34,9 @@ export class HttpClient {
     return await this.request("POST", url, JSON.stringify(json), headers);
   }
 
+  /**
+  * Permform a PUT request
+  */
   async put(
     url: string,
     json: object = {},
@@ -36,6 +48,9 @@ export class HttpClient {
     return await this.request("PUT", url, JSON.stringify(json), headers);
   }
 
+  /**
+  * Permform a PATCH request
+  */
   async patch(
     url: string,
     json: object = {},
@@ -47,6 +62,9 @@ export class HttpClient {
     return await this.request("PATCH", url, JSON.stringify(json), headers);
   }
 
+  /**
+  * Permform a DELETE request
+  */
   async delete(
     url: string,
     json: object = {},
@@ -95,6 +113,9 @@ export class HttpClient {
     return new HttpClientResponse(f.status, await f.json(), f.headers);
   }
 
+  /**
+  * Obtain a valid bearer token
+  */
   async getToken(): Promise<string> {
     if (this.storage.expiresIn === null) {
       const auth = await globalThis.fetch(
@@ -152,6 +173,9 @@ export class HttpClient {
   }
 }
 
+/**
+* HttpClientResponse is the response object of the HttpClient
+*/
 export class HttpClientResponse {
   constructor(
     public statusCode: number,

packages/app-server-sdk/jsr.json

@@ -0,0 +1,5 @@
+{
+  "name": "@friendsofshopware/app-server",
+  "version": "0.0.48",
+  "exports": "./mod.ts"
+}

packages/app-server-sdk/mod.ts

@@ -1,7 +1,5 @@
 export { AppServer } from "./app.ts";
-export type { AppConfigurationInterface } from "./app.ts";
 export { InMemoryShopRepository, SimpleShop, DenoKVRepository } from "./repository.ts"
 export type { ShopInterface, ShopRepositoryInterface } from "./repository.ts"
 export { HttpClient, HttpClientResponse, ApiClientAuthenticationFailed, ApiClientRequestFailed } from "./http-client.ts"
-export { WebCryptoHmacSigner } from "./signer.ts"
 export { Context } from "./context-resolver.ts"

packages/app-server-sdk/registration.ts

@@ -3,6 +3,11 @@ import { AppServer } from "./app.ts";
 export class Registration {
   constructor(private app: AppServer) {}
 
+  /**
+  * This method checks the request for the handshake with the Shopware Shop.
+  * if it's valid a Shop will be created, and a proof will be responded with a confirmation url.
+  * then the Shop will call the confirmation url, and this should be handled by the authorizeCallback method to finish the handshake.
+  */
   public async authorize(req: Request): Promise<Response> {
     const url = new URL(req.url);
 
@@ -52,6 +57,10 @@ export class Registration {
     );
   }
 
+  /**
+  * This method is called by the Shopware Shop to confirm the handshake.
+  * It will update the shop with the given oauth2 credentials.
+  */
   public async authorizeCallback(
     req: Request
   ): Promise<Response> {

packages/app-server-sdk/repository.ts

@@ -1,3 +1,6 @@
+/**
+* ShopInterface defines the object that given back from the ShopRepository, it should methods to get the shop data and set them
+*/
 export interface ShopInterface {
   getShopId(): string;
   getShopUrl(): string;
@@ -7,6 +10,10 @@ export interface ShopInterface {
   setShopCredentials(clientId: string, clientSecret: string): void;
 }
 
+/**
+* ShopRepositoryInterface is the storage interface for the shops, you should implement this to save the shop data to your database
+* For testing cases the InMemoryShopRepository can be used
+*/
 export interface ShopRepositoryInterface {
   createShopStruct(shopId: string, shopUrl: string, shopSecret: string): ShopInterface;
 
@@ -19,6 +26,9 @@ export interface ShopRepositoryInterface {
   deleteShop(id: string): Promise<void>;
 }
 
+/**
+* SimpleShop is a simple implementation of the ShopInterface, it stores the shop data in memory
+*/
 export class SimpleShop implements ShopInterface {
   private shopId: string;
   private shopUrl: string;
@@ -70,7 +80,7 @@ export class InMemoryShopRepository implements ShopRepositoryInterface {
     this.storage.set(shop.getShopId(), shop);
   }
 
-  async getShopById(id: string) {
+  async getShopById(id: string): Promise<ShopInterface|null> {
     if (this.storage.has(id)) {
       return this.storage.get(id) as ShopInterface;
     }
@@ -87,6 +97,9 @@ export class InMemoryShopRepository implements ShopRepositoryInterface {
   }
 }
 
+/**
+* DenoKVRepository is a ShopRepositoryInterface implementation that uses the Deno KV storage to save the shop data
+*/
 export class DenoKVRepository implements ShopRepositoryInterface {
   constructor(private namespace = "shops") {}
 
@@ -143,4 +156,3 @@ export class DenoKVRepository implements ShopRepositoryInterface {
     await kv.delete([this.namespace, id]);
   }
 }
-

packages/app-server-sdk/scripts/build.ts

@@ -14,17 +14,17 @@ export class WebCryptoHmacSigner {
     );
   }
 
-  async verifyGetRequest(request: Request, secret: string) {
+  async verifyGetRequest(request: Request, secret: string): Promise<boolean> {
     const url = new URL(request.url);
     const signature = url.searchParams.get("shopware-shop-signature") as string;
     url.searchParams.delete("shopware-shop-signature");
 
     return await this.verify(signature, url.searchParams.toString(), secret);
   }
 
-  async getKeyForSecret(secret: string) {
+  async getKeyForSecret(secret: string): Promise<CryptoKey> {
     if (this.keyCache.has(secret)) {
-      return this.keyCache.get(secret);
+      return this.keyCache.get(secret) as CryptoKey;
     }
 
     const secretKeyData = this.encoder.encode(secret);
@@ -41,7 +41,7 @@ export class WebCryptoHmacSigner {
     return key;
   }
 
-  async sign(message: string, secret: string) {
+  async sign(message: string, secret: string): Promise<string> {
     const key = await this.getKeyForSecret(secret);
 
     const mac = await crypto.subtle.sign(
@@ -53,13 +53,13 @@ export class WebCryptoHmacSigner {
     return this.buf2hex(mac);
   }
 
-  async verify(signature: string, data: string, secret: string) {
+  async verify(signature: string, data: string, secret: string): Promise<boolean> {
     const signed = await this.sign(data, secret);
 
     return signature === signed;
   }
 
-  buf2hex(buf: any) {
+  buf2hex(buf: ArrayBuffer): string {
     return Array.prototype.map.call(
       new Uint8Array(buf),
       (x) => (("00" + x.toString(16)).slice(-2)),