init commit for iPAL-kit plugin

docs/access.md

@@ -0,0 +1,79 @@
+# access
+
+Kontrola dostępu oparta na rolach: hierarchia **admin > editor > user**.
+Plugin wstrzykuje sztywne pole `roles` do klienckiej kolekcji auth i dostarcza
+predykaty oraz gotowe funkcje dostępu (collection-level i field-level).
+
+## Config (payload.config.ts)
+
+```ts
+ipalKit({
+  access: {
+    authCollection: 'users',   // slug Twojej kolekcji auth
+    // defaultRole: 'user',     // rola nowych użytkowników, domyślnie 'user'
+  },
+})
+```
+
+Wstrzykuje pole `roles` (select hasMany, `saveToJWT`, tylko admin może
+zmieniać role) do wskazanej kolekcji. Kolekcja należy do Ciebie
+(create-payload-app) — plugin tylko dokłada pole.
+
+> Po dodaniu: zadbaj, by seed / pierwszy user miał `roles: ['admin']`, inaczej
+> stracisz dostęp do zasobów admin-only (np. SiteIntegrations).
+
+## Predykaty (front / hooki / access)
+
+```ts
+import { isAdmin, isEditor, hasMinimumRole } from 'ipal-kit'
+
+isAdmin(user)                       // admin?
+isEditor(user)                      // editor lub admin (hierarchia)
+hasMinimumRole(user, 'editor')      // co najmniej editor
+```
+
+Przyjmują luźno typowanego usera (jak `req.user`), czytają `roles` defensywnie.
+
+## Gotowe funkcje dostępu
+
+### Collection-level (zwracają boolean | Where)
+
+```ts
+import { adminOnly, adminOrEditor, adminOrSelf, requireRole, authenticated } from 'ipal-kit'
+
+export const Articles = {
+  slug: 'articles',
+  access: {
+    read: authenticated,
+    create: adminOrEditor,
+    update: adminOrEditor,
+    delete: adminOnly,
+  },
+  // ...
+}
+
+// Users: każdy widzi siebie, admin widzi wszystkich
+access: { read: adminOrSelf }
+
+// dowolny minimalny próg
+access: { update: requireRole('editor') }
+```
+
+### Field-level (zwracają boolean)
+
+```ts
+import { adminOnlyField, adminOrEditorField, requireRoleField } from 'ipal-kit'
+
+{
+  name: 'internalNote',
+  type: 'textarea',
+  access: { read: adminOnlyField, update: adminOnlyField },
+}
+```
+
+## Hierarchia
+
+```ts
+import { ROLE_HIERARCHY } from 'ipal-kit'
+// ['user', 'editor', 'admin'] — wyższa rola spełnia wymóg niższej
+```