@innspel/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niclas Amundsen
+
+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

@@ -0,0 +1,166 @@
+# @innspel/core
+
+Kjernen i Innspels SDK. Ren TypeScript: ingen nettleser-API-er, ingen
+runtime-avhengigheter (K19), ingen stabil identifikator på enheten (K20).
+Lagring og identitet injiseres av verten.
+
+Bygger du en React Native-app, installer [`@innspel/react-native`](../react-native)
+i stedet — den gir deg widgeten og en lagringsadapter, og bruker denne pakken under.
+
+```bash
+npm install @innspel/core
+```
+
+## Quickstart
+
+```ts
+import { init } from '@innspel/core';
+
+const innspel = init({
+  baseUrl: 'https://api.innspel.example',      // din plattform-URL
+  tenantKey: 'ik_pub_xxxxxxxx',                // offentlig SDK-nøkkel fra panelet
+  identityProvider: hentFeedbackToken,         // eller null = anonym modus
+  storage,                                     // se «Lagring» under
+  context: { platform: 'ios', appVersion: '1.4.2' },
+});
+
+await innspel.capture({ type: 'feil', text: 'Dørlista er tom etter kl. 22.' });
+```
+
+Det er hele veien til første innsending. Alt annet under er valgfritt.
+
+## De fire opsjonene du må gi
+
+| Opsjon | Hva |
+|---|---|
+| `baseUrl` | Plattformens API-rot. Ingen standard — SDK-et skal aldri gjette hvor dataene dine havner. |
+| `tenantKey` | Den offentlige SDK-nøkkelen. Skrivende, bundet til bundle-ID eller origin, kan aldri lese andres data (K3). Den hører hjemme i appens konfig, ikke i en hemmelighet. |
+| `identityProvider` | Funksjon som gir et ferskt feedback-token, eller `null` for anonym modus. Se under. |
+| `storage` | Tre metoder. Offline-køen bor her. |
+
+`context.platform` er påkrevd; `appVersion`, `build`, `os`, `screen` og `locale` er
+valgfrie. Feltlista er en **lukket hviteliste** (K5) — et ukjent felt avvises av
+plattformen med `unknown_field`, og SDK-et sender aldri enhets-ID eller IP.
+
+### Identitet
+
+Plattformen eier aldri sluttbrukerne dine. Du utsteder et kortlevd token, den
+verifiserer det og lærer aldri hvem det peker på:
+
+```ts
+const hentFeedbackToken = async () => {
+  const res = await fetch('https://din-app.example/api/innspel-token', {
+    headers: { Authorization: `Bearer ${dinEgenSesjon}` },
+  });
+  return (await res.json()).token;    // ES256-JWT, aud=innspel, exp ≤ 15 min
+};
+```
+
+Token-endepunktet er det eneste du må bygge selv.
+[Integrasjonsguiden](../../../docs/sdk/README.md) viser det med kjørbar kode.
+
+`identityProvider: null` er **anonym modus**: innsendinger sendes uten avsender,
+teller aldri i distinkt Reach og kan ikke følges opp. Det er et eksplisitt valg —
+en glemt opsjon gir en feilmelding, aldri stille anonymitet.
+
+Kaster funksjonen din, eller returnerer den `null`, faller SDK-et tilbake til
+anonym modus for det kallet og logger `[innspel]` til konsollen. Innsenderen skal
+kunne melde fra selv om innloggingen din er nede.
+
+### Lagring
+
+```ts
+interface InnspelStorage {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+```
+
+Bruk hva du vil — MMKV, AsyncStorage, SQLite, et objekt i minnet.
+`@innspel/react-native` gir deg en ferdig.
+
+## API
+
+```ts
+innspel.capture({ type, text, context?, correlation?, relatedKnownIssueId?, clientRef? })
+innspel.knownIssues.for({ screen?, version?, platform? })   // kortene som vises FØR feltet
+innspel.knownIssues.confirm(id)                             // «Ja, jeg også» — Reach +1, ingen ny sak
+innspel.subjects.submissions()                              // «Mine innspill», inkl. det som venter på nett
+innspel.subjects.status(submissionId)                       // status for én egen innsending
+innspel.programs.list()                                     // invitasjoner, deltakelser, oppfølginger
+innspel.queue.pending()                                     // det som ligger i offline-køen
+innspel.queue.flush()                                       // sendes ellers automatisk
+innspel.scanText(text)                                      // mønstervarsel, se under
+innspel.openFeedback()                                      // krever @innspel/react-native
+```
+
+Alt er dokumentert med TSDoc i editoren din. Typene er generert fra API-kontrakten,
+så feltdokumentasjonen er den samme som plattformen håndhever.
+
+### Offline-køen
+
+Faller nettet, køes innsendingen lokalt — **kun teksten**, aldri et skjermbilde.
+Taket er 30; innsending nummer 31 avvises med en synlig melding i stedet for å
+kaste den eldste (DD-41). Køen tømmes når widgeten åpnes eller nettet kommer
+tilbake, **aldri ved oppstart**, og hver flush henter et ferskt token — det gamle
+er utløpt for lengst.
+
+Vis køen for brukeren. `queue.pending()` gir deg radene, og «Venter på nett —
+sendes automatisk» er teksten widgeten bruker.
+
+### Mønstervarsel
+
+```ts
+innspel.scanText('Kontoen min er kari@example.com');
+// [{ kind: 'email', match: 'kari@example.com', start: 15, end: 32 }]
+```
+
+Finner e-post, telefonnummer, kortnummer (Luhn-validert), IP-adresser og
+token-lignende strenger. **Den fjerner aldri noe** (DD-46) — du viser funnet,
+brukeren velger «Fjern» eller «Behold». Innsenderen skal alltid se hva som sendes.
+
+### Telemetri
+
+```ts
+init({ …, telemetry: { emit: (e) => minAnalytics.track(e.name, e) } });
+```
+
+Standard er `noop`. Hendelsene bærer aldri tekst, skjermbilde eller pseudonym.
+Utelater du opsjonen, sendes ingenting noe sted.
+
+## Feil
+
+Alt fra plattformen kommer som `InnspelApiError` med en `code` du kan forgrene på —
+aldri på meldingsteksten:
+
+```ts
+try {
+  await innspel.capture({ type: 'feil', text });
+} catch (e) {
+  if (e instanceof InnspelApiError && e.code === 'text_too_short') { … }
+}
+```
+
+`feedback_token_expired` håndteres internt: SDK-et ber `identityProvider` om et
+nytt token og prøver på nytt, én gang. Den ser du aldri.
+
+## Versjoner
+
+Semver fra `0.1.0`. **Før `1.0.0` kan en minor bryte** — pin en eksakt versjon om
+du trenger ro. Endringer i API-kontrakten er alltid minst minor, fordi de er en
+SDK-endring hos deg.
+
+## Grenser SDK-et holder
+
+- Ingen tredjeparts-SDK: ingen analytics, ingen crash-rapportering, ingen annonser (K19)
+- Ingen install-ID, ingen device-ID, ingen fingeravtrykk (K20). `clientRef` er en ny
+  UUID per innsending og identifiserer aldri enheten
+- Ingen nettleser-API-er: `localStorage`, `document`, `window` og `navigator` finnes
+  ikke i denne pakken
+- Under 10 kB gzip
+
+## Lisens
+
+MIT. Klientpakkene er permissivt lisensiert fordi koden kjører hos deg og må
+kunne leses og granskes der. Plattformen bak — API, panel og drift — er det ikke.