scanoss

type ChunkError struct {
	// Index is the zero-based position of the failed chunk.
	Index int
	// Err is the underlying error.
	Err error
}

type Client struct {

	// Decoration services (grouped public API). Wired in New.
	Vulnerabilities VulnerabilityAPI
	Licenses        LicenseAPI
	Cryptography    CryptographyAPI
	Geoprovenance   GeoprovenanceAPI
	Copyright       CopyrightAPI
	Components      ComponentsAPI
	Dependencies    DependencyAPI

	// Scan service (batch WFP scanning). Wired in New.
	Scan ScanAPI
	// contains filtered or unexported fields
}

type Component struct {
	Purl        string `json:"purl"`
	Requirement string `json:"requirement,omitempty"`
}

type ComponentSearch struct {
	Search    string // free-form term; overrides Vendor/Component when set
	Vendor    string
	Component string
	PurlType  string // purl type (github, npm, pypi, …); defaults to github server-side
	Limit     int    // max results (0 = server default)
	Offset    int    // pagination offset
}

type ComponentsAPI interface {
	Search(ctx context.Context, q ComponentSearch) (*scanossapi.ComponentsSearchResponse, error)
	Versions(ctx context.Context, purl string, limit int) (*scanossapi.ComponentVersionsResponse, error)
	Status(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.ComponentsStatusResponse, error)
	StatusOne(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.ComponentsStatusResponse, error)
}

type Config struct {
	// APIKey authenticates the requests. Empty means keyless, which the public
	// endpoint rejects and an on-prem one may allow.
	APIKey string
	// APIURL is the API base URL (default DefaultAPIURL). A trailing slash is trimmed.
	APIURL string

	// Proxy overrides HTTP_PROXY and HTTPS_PROXY for this client. It needs an http://
	// or https:// scheme; NO_PROXY still applies. Empty leaves Go's own environment
	// handling in place.
	Proxy string
	// CACertFile is a PEM file whose certificates are trusted in addition to the system
	// pool. Verification stays on: this adds an authority, it does not stop checking.
	CACertFile string
	// InsecureTLS disables certificate verification entirely. For self-signed or
	// internal endpoints only; prefer CACertFile, which keeps verification on.
	InsecureTLS bool
	// Timeout bounds one request attempt, body transfer included (default
	// DefaultTimeout). A negative value disables it. Retry-After waits happen between
	// attempts, so this does not cut them short.
	Timeout time.Duration

	// ChunkSize is the number of PURLs per decoration request (default
	// DefaultChunkSize), shared by every decoration service.
	ChunkSize int
	// Workers caps the concurrent requests (default DefaultWorkers). The effective
	// number is never larger than the number of chunks.
	Workers int
	// MaxRetries caps the retry count when the server answers 429/503 with a
	// Retry-After header (default DefaultMaxRetries).
	MaxRetries int
	// MaxRetryAfter caps a single Retry-After wait (default DefaultMaxRetryAfter),
	// bounding a pathological server value.
	MaxRetryAfter time.Duration

	// Logger receives the SDK's diagnostics, at Debug/Info/Warn (default
	// slog.Default()). The SDK never writes to stdout, only through this logger.
	Logger *slog.Logger
}

type CopyrightAPI interface {
	Evidence(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CopyrightEvidenceResponse, error)
	Holders(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CopyrightHoldersResponse, error)
}

type CryptographyAPI interface {
	Algorithms(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CryptoAlgorithmsResponse, error)
	Algorithm(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.CryptoAlgorithmsResponse, error)
	AlgorithmsInRange(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CryptoAlgorithmsInRangeResponse, error)
	AlgorithmInRange(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.CryptoAlgorithmsInRangeResponse, error)
	VersionsInRange(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CryptoVersionsInRangeResponse, error)
	VersionInRange(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.CryptoVersionsInRangeResponse, error)
	Hints(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CryptoHintsResponse, error)
	Hint(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.CryptoHintsResponse, error)
	HintsInRange(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CryptoHintsInRangeResponse, error)
	HintInRange(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.CryptoHintsInRangeResponse, error)
}

type DecorateOption func(*decorateOptions)

type DecorationPipeline struct {
	// contains filtered or unexported fields
}

type DecorationReporter interface {
	// Decorating reports one service's advance over the components, counted in PURLs. Services run
	// concurrently, so updates from several arrive interleaved, each tagged with its own name
	// (Service.Name, e.g. "licenses" or "cryptography.algorithms").
	Decorating(service string, done, total int)
}

type DependencyAPI interface {
	// Dependencies resolves declared dependencies + licenses for the given
	// components (batch POST).
	Dependencies(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.DependenciesResolveResponse, error)
	// Dependency resolves declared dependencies for a single component (GET).
	Dependency(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.DependenciesResolveResponse, error)
	// Transitive walks declared dependencies bounded by depth and limit (POST).
	// depth/limit <= 0 are omitted so the server defaults apply.
	Transitive(ctx context.Context, comps []Component, depth, limit int) (*scanossapi.TransitiveResponse, error)
}

type GeoprovenanceAPI interface {
	Origins(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.GeoOriginResponse, error)
	Origin(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.GeoOriginResponse, error)
	Countries(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.GeoContributorsResponse, error)
	Country(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.GeoContributorsResponse, error)
}

type LicenseAPI interface {
	Attribution(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.AttributionResponse, error)
	Evidence(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.LicenseEvidenceResponse, error)
	Components(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.ComponentsLicenseResponse, error)
	Component(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.ComponentLicenseResponse, error)
	Details(ctx context.Context, license string) (*scanossapi.LicenseDetailsResponse, error)
	Obligations(ctx context.Context, license string) (*scanossapi.ObligationsResponse, error)
}

type PipelineResult struct {
	Services map[string]*Result // keyed by service name; full per-service result
	Errors   map[string]error   // services that failed entirely
}

type Result struct {

	// Failed lists the chunks that did not succeed, if any.
	Failed []ChunkError
	// contains filtered or unexported fields
}

type ScanAPI interface {
	// Folder collects, fingerprints and scans a directory tree (or single file).
	Folder(ctx context.Context, path string, opts ...ScanOption) (scanossapi.ScanEnvelope, error)

	// Files fingerprints and scans an explicit list of files.
	Files(ctx context.Context, files []string, opts ...ScanOption) (scanossapi.ScanEnvelope, error)

	// WFP scans an already-assembled WFP byte stream.
	WFP(ctx context.Context, wfp []byte, opts ...ScanOption) (scanossapi.ScanEnvelope, error)

	// Status performs a single status poll for a known scan id.
	Status(ctx context.Context, scanID string) (scanossapi.ScanEnvelope, error)

	// Wait resumes polling a known scan id until a terminal state. Used to recover
	// an interrupted scan (e.g. `scanoss-cli results <id>`). The poll cadence can be
	// tuned with WithPollInterval.
	Wait(ctx context.Context, scanID string, opts ...ScanOption) (scanossapi.ScanEnvelope, error)
}

type ScanOption func(*scanOptions)

type ScanReporter interface {
	// Fingerprinting reports local hashing as files are hashed. done only ever grows.
	Fingerprinting(done, total int)

	// Uploading reports WFP blocks handed to the server. done only ever grows: it counts 1..total,
	// one call per block, and the last call carries total.
	Uploading(done, total int)

	// Scanning reports one status poll of a running scan, handing over the server's envelope
	// verbatim: the SDK does not choose which of its fields matter.
	//
	// The server scans in passes ("Pass 1: scan files", "Pass 2: scan snippets", ...) that each
	// restart PhaseDone/PhaseTotal and count something different from the last, so those counters
	// are comparable only within one Phase. A caller rendering them as a single bar must segment it
	// by Phase; feeding them straight to one bar makes it run backwards.
	//
	// Polling samples the scan rather than streaming it, so a pass shorter than the poll interval
	// is never reported at all. Whether the scan succeeded is Status, never these counters.
	Scanning(env scanossapi.ScanEnvelope)
}

type Service struct {
	Name string // stable id, used for logging/progress tagging
	// contains filtered or unexported fields
}

type StatusError struct {
	StatusCode int
	Body       string
}

type VulnerabilityAPI interface {
	Components(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.VulnerabilitiesResponse, error)
	Component(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.VulnerabilitiesResponse, error)
	Cpes(ctx context.Context, comps []Component, opts ...DecorateOption) (*scanossapi.CpesResponse, error)
	Cpe(ctx context.Context, comp Component, opts ...DecorateOption) (*scanossapi.CpesResponse, error)
}