@fntio/infra-client-plugin-sdk 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@fntio/infra-client-plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Contracts and runtime for infra-client customer plugins: manifest, catalog, discovery, the iframe SDK and host adapter, authorizer context, validators and test fixtures.",
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FNTIO/aws-infrastructure-client.git",
+    "directory": "packages/infra-client-plugin-sdk"
+  },
+  "homepage": "https://github.com/FNTIO/aws-infrastructure-client/wiki",
+  "bugs": {
+    "url": "https://github.com/FNTIO/aws-infrastructure-client/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./fixtures": {
+      "types": "./dist/fixtures/index.d.ts",
+      "default": "./dist/fixtures/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "dist/browser/index.d.ts"
+      ],
+      "host": [
+        "dist/host/index.d.ts"
+      ],
+      "backend": [
+        "dist/backend/index.d.ts"
+      ],
+      "fixtures": [
+        "dist/fixtures/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "jest"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/*.test.ts"
+    ],
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "tsconfig": "<rootDir>/tsconfig.jest.json"
+        }
+      ]
+    },
+    "maxWorkers": "50%",
+    "workerIdleMemoryLimit": "2GB"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.43",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.5.0"
+  }
+}

package/skills/build-infra-client-plugin/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: build-infra-client-plugin
+description: Build a customer plugin for an infra-client access portal — manifest, permissions, routes, a Lambda handler using the backend SDK, and a frontend using the browser SDK. Use when someone asks to add a plugin, a plugin page, or a plugin API to their portal.
+---
+
+# Build an infra-client plugin
+
+A plugin is a small app the portal hosts: a frontend in an iframe on the portal's own origin, and
+Lambda routes behind the portal's shared authorizer. The portal handles sign-in, which accounts a
+caller may use, theming and permissions. You write the business part.
+
+**Before writing anything, read the installed package's own documentation** — `README.md` in
+`@fntio/infra-client-plugin-sdk`, and the worked example in `@fntio/infra-client-plugin-example`. They
+match the version installed in this project; this file does not restate their API, deliberately, so
+there is one place to maintain.
+
+## Work in the project's own conventions
+
+Inspect before you generate. This skill never introduces a project layout, a build tool or a test
+runner the repository does not already use.
+
+1. How are existing Lambdas written and bundled here? Match it. If the project has its own function
+   construct, use that rather than `NodejsFunction`. A plugin that ships as an installable package is
+   the exception: it prebundles its handler and registers it with `Code.fromAsset`, so the deployment
+   installing it runs no bundler of its own.
+2. What frontend tooling exists? A plugin frontend is an ordinary bundle — any framework or none. Use
+   what the project already builds with.
+3. How are tests written? Mirror the nearest existing suite.
+
+## The shape
+
+1. **Decide the permissions.** Two levels exist: `user` and `admin`. `admin` includes `user` only when
+   the plugin declares `user`. Give each a label an administrator will read in the grant editor.
+2. **Decide the accounts.** A plugin is bound to specific accounts, and one request authorizes exactly
+   one of them. A handler must never act on an account other than the one in its authorizer context —
+   refuse instead, as the example does.
+3. **Write the routes.** Each names a method, a path relative to the account root, the permission it
+   requires, and the handler that serves it. Paths take literal segments and single-segment `{params}`.
+4. **Write the handler.** Take the authorizer context from the event; never re-read a permission, a
+   user or an account from the request. Answer domain 4xx codes for business failures — never 401,
+   which the SDK treats as the authorizer rejecting the caller and retries once.
+5. **Write the frontend.** Connect to the portal, read the accounts the caller may use (which one
+   the page works in is its own state), call your own API through the provided helper. Do not implement a login, store a token, or put one in a URL. Use the component
+   classes from `@fntio/infra-client-plugin-ui` (`applyPluginUi(document)`) rather than styling from
+   scratch — a page built on them matches the portal, and one that is not will look foreign however
+   carefully it is themed.
+6. **Bound the blast radius twice.** Whatever your handler refuses in code, its IAM policy should also
+   refuse. The example scopes both to configured name prefixes.
+
+## Checks before you hand it over
+
+- Type-check and test with the project's own commands.
+- Build the frontend. Registration fails at synth if the entry file is missing.
+- Confirm no secret or parameter value reaches a log line.
+- Confirm a request naming a different account is refused rather than served.
+
+## What this feature does not do
+
+There is no per-resource permission below the account, no automatic IAM for your handler, no generated
+project, and no CLI. Long-running work returns `202` with a job id and is polled by your own routes;
+the platform provides no job runner and no websockets.