Access

Use access queries at application authorization boundaries, after authenticating the merchant customer or member.

import { checkAccess, explainAccess } from "@byfungsi/sapa";
import { Effect } from "effect";

const query = {
  externalCustomerId: "customer-42",
  entitlement: "workspace.use",
} as const;

const program = Effect.all({
  allowed: checkAccess(query),
  explanation: explainAccess(query),
});

checkAccess is the simple boolean gate. explainAccess returns a point-in-time decision:

• granted with supporting paid contribution IDs;
• postpaid_granted with supporting subscription IDs;
• denied because no active contribution exists or postpaid access is suspended.

Finite access is end-exclusive. At exactly validUntil, it is no longer active. Multiple independent contributions can overlap; access remains granted while at least one valid contribution supports the entitlement.

Beneficiaries and seats

checkAccess is customer-entitlement access. For a member occupying beneficiary seat capacity, use checkSeatAssignmentAccess. This query includes the beneficiary, pool, member, and entitlement and fails closed if capacity is inconsistent.

Authorization responsibility

SAPA answers monetization eligibility. Your application still owns identity, session authentication, organization membership, and broader authorization policy. Never let a caller choose another customer’s externalCustomerId without checking that relationship first.