osfapi

package
v1.0.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package osfapi implements the OSF API v2 HTTP client used by the CLI.

Index

Constants

This section is empty.

Variables

View Source 
var ErrRangeUnsupported = errors.New("download range request was not honored")

ErrRangeUnsupported indicates that a provider did not honor a range request.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Method     string
	Path       string
	Title      string
	Detail     string
}

APIError preserves OSF status and error detail fields.

func (*APIError) Error 

func (e *APIError) Error() string

Error returns a human-readable summary of the OSF API error.

type Client 

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

Client is an HTTP client for the OSF API v2 JSON:API surface. It handles authentication, pagination, and JSON deserialization.

func New 

func New(baseURL string, opts ...Option) (*Client, error)

New creates a Client that communicates with the given OSF API base URL. If baseURL is empty, the default production URL (https://api.osf.io/v2/) is used. Returns an error if the URL cannot be parsed.

func (*Client) CreateFolder 

func (c *Client) CreateFolder(ctx context.Context, providerURL, folderName string) error

CreateFolder creates a folder via WaterButler.

func (*Client) CreateNode 

func (c *Client) CreateNode(ctx context.Context, title, category, description string) (Node, error)

CreateNode creates an OSF node with the supplied title, category, and description.

func (*Client) CreateRegistration 

func (c *Client) CreateRegistration(ctx context.Context, nodeID string, request RegistrationRequest) (Node, error)

CreateRegistration creates a draft registration for a node.

func (*Client) CurrentUser 

func (c *Client) CurrentUser(ctx context.Context) (User, error)

CurrentUser returns the authenticated user's profile information. Requires a valid bearer token; returns MissingTokenError otherwise.

func (*Client) DeleteFile 

func (c *Client) DeleteFile(ctx context.Context, providerURL, fileName string) error

DeleteFile deletes a file via WaterButler.

func (*Client) DeleteNode 

func (c *Client) DeleteNode(ctx context.Context, id string) error

DeleteNode deletes an OSF node by ID.

func (*Client) GetNode 

func (c *Client) GetNode(ctx context.Context, id string) (Node, error)

GetNode returns a single node (project or component) by its OSF GUID.

func (*Client) GetNodeFilesProvider 

func (c *Client) GetNodeFilesProvider(ctx context.Context, nodeID string) (string, error)

GetNodeFilesProvider gets the files provider URL for a node's OSF Storage. Returns the provider URL for use with WaterButler operations.

func (*Client) GetStorageFile 

func (c *Client) GetStorageFile(ctx context.Context, id string) (StorageFile, error)

GetStorageFile returns a single storage file or folder metadata record by its OSF GUID.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context, id string) (User, error)

GetUser returns a user profile by OSF user ID.

func (*Client) ListCurrentUserProjects 

func (c *Client) ListCurrentUserProjects(ctx context.Context) ([]Node, error)

ListCurrentUserProjects returns all project-category nodes owned by the current user. Automatically follows pagination links. Requires a bearer token.

func (*Client) ListFileVersions 

func (c *Client) ListFileVersions(ctx context.Context, fileID string) ([]FileVersion, error)

ListFileVersions loads all versions for a file.

func (*Client) ListNodeAddons 

func (c *Client) ListNodeAddons(ctx context.Context, id string) ([]Node, error)

ListNodeAddons lists all storage add-ons configured for a node.

func (*Client) ListNodeChildren 

func (c *Client) ListNodeChildren(ctx context.Context, id string) ([]Node, error)

ListNodeChildren returns all immediate child components of the specified node. Automatically follows pagination links.

func (*Client) ListNodeComments 

func (c *Client) ListNodeComments(ctx context.Context, id string) ([]RelatedResource, error)

ListNodeComments loads comments linked to a node.

func (*Client) ListNodeContributors 

func (c *Client) ListNodeContributors(ctx context.Context, id string) ([]Contributor, error)

ListNodeContributors returns all contributors for the specified node. Automatically follows pagination links.

func (*Client) ListNodeIdentifiers 

func (c *Client) ListNodeIdentifiers(ctx context.Context, id string) ([]RelatedResource, error)

ListNodeIdentifiers loads identifiers linked to a node.

func (*Client) ListNodeLogs 

func (c *Client) ListNodeLogs(ctx context.Context, id string) ([]RelatedResource, error)

ListNodeLogs loads audit log entries linked to a node.

func (*Client) ListNodeRegistrations 

func (c *Client) ListNodeRegistrations(ctx context.Context, id string) ([]Node, error)

ListNodeRegistrations loads registrations linked to a node.

func (*Client) ListPreprints 

func (c *Client) ListPreprints(ctx context.Context, provider string, limit ...int) ([]Node, error)

ListPreprints loads preprints visible to the current request context.

func (*Client) ListStorageFiles 

func (c *Client) ListStorageFiles(ctx context.Context, nodeID string, segments ...string) ([]StorageFile, error)

ListStorageFiles returns all files and folders from a node's OSF Storage provider. Additional path segments can be provided to navigate into subfolders. Automatically follows pagination links.

func (*Client) ListWikiPages 

func (c *Client) ListWikiPages(ctx context.Context, id string) ([]RelatedResource, error)

ListWikiPages loads wiki pages linked to a node.

func (*Client) OpenDownload 

func (c *Client) OpenDownload(ctx context.Context, downloadURL string) (io.ReadCloser, error)

OpenDownload opens the given download URL and returns the response body. The caller is responsible for closing the returned io.ReadCloser.

func (*Client) OpenDownloadRange added in v1.0.0 

func (c *Client) OpenDownloadRange(ctx context.Context, downloadURL string, offset int64) (io.ReadCloser, error)

OpenDownloadRange opens a download at offset. Providers that ignore the range request return ErrRangeUnsupported so callers can restart safely.

func (*Client) ResolveDOI added in v1.0.0 

func (c *Client) ResolveDOI(ctx context.Context, identifier string) (DOIResolution, error)

ResolveDOI resolves an OSF DOI without using the OSF API credentials.

func (*Client) SearchOSF 

func (c *Client) SearchOSF(ctx context.Context, query string, limit ...int) ([]SearchResult, error)

SearchOSF performs a search across OSF content.

func (*Client) SearchPreprints added in v1.0.0 

func (c *Client) SearchPreprints(ctx context.Context, query, provider string, limit ...int) ([]Preprint, error)

SearchPreprints searches OSF preprints by title and optionally provider.

func (*Client) UpdateNode 

func (c *Client) UpdateNode(ctx context.Context, id, title, description string) (Node, error)

UpdateNode updates title and description metadata for an OSF node.

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, providerURL, fileName string, content io.Reader, conflict string) error

UploadFile uploads content to a storage provider via WaterButler. The providerURL is typically obtained from GET /v2/nodes/{id}/files/osfstorage/ and looks like "https://files.osf.io/v1/providers/osfstorage/..."

type Contributor 

type Contributor struct {
	ID         string                `json:"id"`
	Type       string                `json:"type"`
	Attributes ContributorAttributes `json:"attributes"`
	Links      Links                 `json:"links"`
}

Contributor models a node contributor entry.

type ContributorAttributes 

type ContributorAttributes struct {
	FullName      string `json:"full_name"`
	Bibliographic bool   `json:"bibliographic"`
	Permission    string `json:"permission,omitempty"`
}

ContributorAttributes carries contributor display and permission metadata.

type DOIResolution added in v1.0.0 

type DOIResolution struct {
	DOI         string `json:"doi"`
	ResolvedURL string `json:"resolved_url"`
}

DOIResolution describes a DOI that resolved to an OSF web resource.

func ResolveDOI added in v1.0.0 

func ResolveDOI(ctx context.Context, identifier string) (DOIResolution, error)

ResolveDOI resolves an OSF DOI or DOI URL and rejects non-OSF destinations. It follows normal HTTP redirects but never treats an arbitrary DOI target as an OSF resource.

type FileVersion 

type FileVersion struct {
	ID         string                `json:"id"`
	Type       string                `json:"type"`
	Attributes FileVersionAttributes `json:"attributes"`
	Links      Links                 `json:"links"`
}

FileVersion represents a version of an OSF storage file.

type FileVersionAttributes 

type FileVersionAttributes struct {
	Size         int64     `json:"size,omitempty"`
	DateCreated  time.Time `json:"date_created,omitempty"`
	DateModified time.Time `json:"date_modified,omitempty"`
}

FileVersionAttributes carries size and timestamp metadata for a file version. 

type Links struct {
	Self     string `json:"self,omitempty"`
	HTML     string `json:"html,omitempty"`
	Next     string `json:"next,omitempty"`
	Prev     string `json:"prev,omitempty"`
	Related  string `json:"related,omitempty"`
	Download string `json:"download,omitempty"`
}

Links carries the JSON:API link set used by OSF responses.

type Node 

type Node struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	Attributes NodeAttributes `json:"attributes"`
	Links      Links          `json:"links"`
}

Node models OSF projects and components.

type NodeAttributes 

type NodeAttributes struct {
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Category    string   `json:"category,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	DateCreated string   `json:"date_created,omitempty"`
}

NodeAttributes carries display and category fields for OSF nodes.

type Option 

type Option func(*Client)

Option configures a Client using the functional options pattern.

func WithBearerToken 

func WithBearerToken(token string) Option

WithBearerToken sets the Authorization header for API requests.

func WithCredentials 

func WithCredentials(credentials auth.Credentials) Option

WithCredentials sets the OSF credential mode for API requests.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the HTTP client used for API requests. If nil, a client with the default OSF timeout is used.

func WithObserver added in v1.0.0 

func WithObserver(emitter observability.Emitter) Option

WithObserver enables redacted structured request events.

func WithUsernamePassword 

func WithUsernamePassword(username, password string) Option

WithUsernamePassword sets HTTP Basic request signing credentials.

type Preprint added in v1.0.0 

type Preprint struct {
	ID         string             `json:"id"`
	Type       string             `json:"type"`
	Attributes PreprintAttributes `json:"attributes"`
	Links      Links              `json:"links"`
}

Preprint models an OSF preprint result with discovery metadata.

type PreprintAttributes added in v1.0.0 

type PreprintAttributes struct {
	Title         string `json:"title"`
	DatePublished string `json:"date_published,omitempty"`
	IsPublished   bool   `json:"is_published"`
	DOI           string `json:"doi,omitempty"`
}

PreprintAttributes carries the fields exposed by the OSF preprint search API.

type RegistrationRequest 

type RegistrationRequest struct {
	SchemaID    string `json:"schemaId"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
}

RegistrationRequest describes the draft registration fields submitted for a node.

type RelatedResource added in v1.0.0 

type RelatedResource struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	Attributes map[string]any `json:"attributes,omitempty"`
	Links      Links          `json:"links"`
}

RelatedResource models a JSON:API resource linked from an OSF node. Attributes remain structured JSON because OSF uses different fields for wiki pages, comments, logs, identifiers, and provider add-ons.

type SearchResult 

type SearchResult struct {
	ID          string   `json:"id"`
	Type        string   `json:"type"`
	Title       string   `json:"title,omitempty"`
	Description string   `json:"description,omitempty"`
	Category    string   `json:"category,omitempty"`
	URL         string   `json:"url,omitempty"`
	Keywords    []string `json:"keywords,omitempty"`
	Year        string   `json:"year,omitempty"`
}

SearchResult models one OSF search result across supported resource types.

type StorageFile 

type StorageFile struct {
	ID         string                `json:"id"`
	Type       string                `json:"type"`
	Attributes StorageFileAttributes `json:"attributes"`
	Links      Links                 `json:"links"`
}

StorageFile models OSF Storage file and folder entries.

func (StorageFile) DownloadURL 

func (f StorageFile) DownloadURL() string

DownloadURL returns the file download URL when OSF provides one.

type StorageFileAttributes 

type StorageFileAttributes struct {
	Name  string           `json:"name"`
	Kind  string           `json:"kind"`
	Size  int64            `json:"size,omitempty"`
	Extra StorageFileExtra `json:"extra,omitempty"`
}

StorageFileAttributes carries OSF Storage file metadata.

type StorageFileExtra added in v1.0.0 

type StorageFileExtra struct {
	Hashes StorageFileHashes `json:"hashes,omitempty"`
}

StorageFileExtra carries provider metadata returned for a storage entry.

type StorageFileHashes added in v1.0.0 

type StorageFileHashes struct {
	MD5 string `json:"md5,omitempty"`
}

StorageFileHashes carries optional integrity hashes for a storage entry.

type User 

type User struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	Attributes UserAttributes `json:"attributes"`
	Links      Links          `json:"links"`
}

User models the OSF current user response.

type UserAttributes 

type UserAttributes struct {
	FullName   string `json:"full_name"`
	GivenName  string `json:"given_name,omitempty"`
	FamilyName string `json:"family_name,omitempty"`
}

UserAttributes carries profile fields returned for an OSF user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.